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

---
id: wiki-2026-0508-t-component-tool-registry
title: T-component (Tool Registry)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Tool Registry, Tool Catalog, Agent Tools, T-component]
duplicate_of: none
source_trust_level: A
confidence_score: 0.85
verification_status: applied
tags: [agent, tools, llm, architecture]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: 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
```ts
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
```ts
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
```ts
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
```ts
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)
```ts
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
```ts
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)
```ts
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
```ts
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 |