2nd/10_Wiki/Topics/Backend/T-component (Tool Registry).md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-t-component-tool-registry	T-component (Tool Registry)	10_Wiki/Topics	verified	self	Tool Registry Tool Catalog Agent Tools T-component	none	A	0.85	applied	agent tools llm architecture		2026-05-10	pending	language framework typescript anthropic-sdk/mcp

T-component (Tool Registry)

매 한 줄

"매 LLM agent 가 호출 가능한 tool 들의 declared 카탈로그 + dispatcher". 매 OpenAI function calling 2023, 매 Anthropic tool use 2024, 매 MCP (Model Context Protocol) 2024 표준화 의 evolution. 매 6-component pattern (S/T/L/I/M/E) 의 T 핵심. 매 2026 의 production agent 는 100+ tools 의 dynamic loading.

매 핵심

매 책임

• Schema declaration: name, description, JSON-schema params.
• Discovery: LLM 의 selection 을 위한 metadata.
• Permissions: per-tool ACL (read/write, sandbox).
• Dispatch: tool_use → handler invocation.
• Result formatting: stringify for LLM consumption.

매 patterns

• Static: hardcoded list at startup.
• Dynamic: runtime registration (plugin).
• MCP server: external process, JSON-RPC.
• Hierarchical: meta-tool 으로 search/load 다른 tools.

매 응용

1. Coding agent (Read, Edit, Bash, Grep, ...).
2. Research agent (WebSearch, WebFetch, ...).
3. Customer support agent (CRM tools).
4. RPA / browser automation.

💻 패턴

Anthropic tool definition

const tools = [
  {
    name: 'read_file',
    description: 'Read contents of a file from disk.',
    input_schema: {
      type: 'object',
      properties: {
        path: { type: 'string', description: 'Absolute file path' },
        offset: { type: 'integer', description: 'Start line (optional)' },
        limit: { type: 'integer', description: 'Max lines (optional)' },
      },
      required: ['path'],
    },
  },
  // ... more
];

const resp = await client.messages.create({
  model: 'claude-opus-4-7',
  max_tokens: 4096,
  tools,
  messages,
});

Registry class

type ToolHandler = (input: any, ctx: ToolContext) => Promise<string>;

class ToolRegistry {
  private tools = new Map<string, { def: ToolDef; handler: ToolHandler }>();

  register(def: ToolDef, handler: ToolHandler) {
    if (this.tools.has(def.name)) throw new Error(`dup: ${def.name}`);
    this.tools.set(def.name, { def, handler });
  }

  list(): ToolDef[] { return [...this.tools.values()].map(t => t.def); }

  async dispatch(name: string, input: any, ctx: ToolContext): Promise<string> {
    const t = this.tools.get(name);
    if (!t) throw new Error(`unknown tool: ${name}`);
    if (!ctx.allowed(name)) throw new Error(`denied: ${name}`);
    return await t.handler(input, ctx);
  }
}

Permission gating

type Permission = 'read' | 'write' | 'exec';
const TOOL_PERMS: Record<string, Permission> = {
  read_file: 'read',
  edit_file: 'write',
  bash: 'exec',
};

class ToolContext {
  constructor(private granted: Set<Permission>) {}
  allowed(name: string) {
    const perm = TOOL_PERMS[name];
    return perm ? this.granted.has(perm) : false;
  }
}

Loop with tool dispatch

let messages: Message[] = [{ role: 'user', content: userQuery }];
while (true) {
  const resp = await client.messages.create({ model, tools: registry.list(), messages });
  messages.push({ role: 'assistant', content: resp.content });

  const toolUses = resp.content.filter(b => b.type === 'tool_use');
  if (resp.stop_reason !== 'tool_use' || toolUses.length === 0) break;

  const results = await Promise.all(toolUses.map(async tu => ({
    type: 'tool_result' as const,
    tool_use_id: tu.id,
    content: await registry.dispatch(tu.name, tu.input, ctx),
  })));
  messages.push({ role: 'user', content: results });
}

MCP server (external tool)

import { Server } from '@modelcontextprotocol/sdk/server';

const server = new Server({ name: 'fs-tools', version: '1.0' });

server.tool('read_file', {
  description: 'Read file',
  parameters: z.object({ path: z.string() }),
}, async ({ path }) => {
  return { content: [{ type: 'text', text: await fs.readFile(path, 'utf8') }] };
});

await server.connect(new StdioServerTransport());

Lazy tool loading

class LazyRegistry extends ToolRegistry {
  private metaTool = {
    name: 'find_tool',
    description: 'Search available tools by keyword. Returns list to load.',
    input_schema: { type: 'object', properties: { query: { type: 'string' }}, required: ['query'] },
  };

  async findTool(query: string): Promise<string[]> {
    return [...this.allTools.keys()].filter(n => n.includes(query));
  }
}

Result truncation (token budget)

function truncate(s: string, maxTokens = 4000): string {
  const approxChars = maxTokens * 4;
  if (s.length <= approxChars) return s;
  return s.slice(0, approxChars / 2) + `\n[... ${s.length - approxChars} chars truncated ...]\n` + s.slice(-approxChars / 2);
}

Tool deprecation flow

registry.register({
  name: 'old_search',
  description: 'DEPRECATED — use web_search instead. Will be removed 2026-Q3.',
  ...
}, async (input) => {
  console.warn('deprecated tool used');
  return registry.dispatch('web_search', input, ctx);
});

매 결정 기준

상황	Approach
< 20 tools	Static list, all in context
20-100 tools	Categories + meta-tool selector
100+ tools	RAG over tool descriptions + lazy load
Cross-process	MCP server
Multi-tenant	Permission gating + audit log

기본값: Anthropic SDK + MCP servers + permission ACL.

🔗 Graph

• 부모: Agent Architecture · Tool Use
• 변형: MCP · Function Calling
• Adjacent: S-component (State Store)

🤖 LLM 활용

언제: tool schema 작성, dispatch boilerplate, permission policy. 언제 X: tool semantic 의 actual 결정 (도메인 지식).

❌ 안티패턴

• Bloated context: 모든 tools 의 always-loaded → token waste.
• No permission: agent 가 destructive ops 수행.
• Vague descriptions: LLM 의 wrong tool selection.
• No timeout: tool hang 의 agent freeze.
• No retries: transient errors 의 task fail.

🧪 검증 / 중복

• Verified (Anthropic tool use docs 2025, MCP spec 2024-2026).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — T-component full coverage