tool-specification

Tool Definition and Integration Patterns (Tool Specification)

R — Original Text (Reading)

Claude Code: ToolSearch for lazy loading, parallel tool calls, Agent tool for sub-agent delegation Claude Chrome: PURL compact command mode, three-tier action classification (Prohibited/Explicit Permission/Regular) GPT-4o: Content Reference System, file_search with citation format ChatGPT Agent Mode: three-channel architecture (analysis/commentary/final), browser+computer+container tools Meta AI: four namespaces (media, browser, meta_1p, container, third_party) with full JSON Schema Grok 4: Custom XML function call format (xai:function_call), code_execution with stateful REPL

I — Methodological Skeleton (Interpretation)

The core design patterns of tool definition and integration comprise five orthogonal dimensions:

1. Definition Format: JSON Schema (Meta AI, Claude), XML (Grok 4's xai:function_call), TypeScript types (Codex) — the format choice affects parsing efficiency and composability.
2. Permission Gating: A three-tier model — Prohibited tier (never executable), Explicit Permission tier (requires user confirmation), Regular tier (automatically executed). Claude Chrome's three-tier classification is the exemplar of this pattern.
3. Discovery Mechanism: When the number of tools is large (Jules 25+, Meta AI's four namespaces), lazy loading (Claude Code's ToolSearch) or namespace grouping (Meta AI's media/browser/meta_1p/container/third_party) is needed.
4. Parallel Execution: Claude Code supports parallel tool calls, Gemini CLI achieves parallel investigation through sub-agent delegation, and ChatGPT Agent achieves parallelism of thinking and action through its three-channel architecture.
5. Lifecycle Management: The complete process of a tool from discovery to execution to result handling. Jules's three-phase lifecycle of plan/review/submit and Codex's Plan tool with skip rules are representatives of this pattern.

A1 — Case Analysis (Past Application)

Case 1: Claude Chrome's Three-Tier Permission Gating

• Problem: Browser operations involve extremely high security risks (payments, deletions, navigating to malicious sites). How can security control be achieved without sacrificing usability?
• Use of the Design Pattern: Classify all browser operations into three tiers — Prohibited (e.g., automatically filling in password fields, never executed), Explicit Permission (e.g., clicking a purchase button, must be confirmed by the user), Regular (e.g., scrolling the page, automatically executed). Combined with the critical_injection_defense security layer, this forms defense in depth.
• Conclusion: Three-tier classification is more flexible than a simple "allow/deny" dichotomy, avoiding excessive restriction while holding the security bottom line.

Case 2: Meta AI's Four-Namespace Tool Architecture

• Problem: Meta's toolset spans media generation, browser operations, first-party services, and third-party plugins. How can this complexity be managed?
• Use of Design Patterns: Divide tools into four namespaces by functional domain, with tools within each namespace sharing a unified JSON Schema definition and permission policy. This grouping approach makes adding new tools a local operation that does not affect other namespaces.
• Conclusion: Namespace grouping is a mandatory strategy when the number of tools exceeds 15; otherwise, the system prompt becomes unmaintainable.

Case 3: Sub-agent Delegation in Gemini CLI

• Problem: How can a single agent efficiently handle complex programming tasks that require parallel investigation?
• Use of Design Patterns: Implement four specialized sub-agents: codebase_investigator, cli_help, generalist, and browser_agent. The main agent acts as the orchestrator, delegating different types of subtasks to specialized sub-agents for parallel execution, and finally aggregating the results.
• Conclusion: The sub-agent delegation pattern significantly outperforms a monolithic agent in complex tasks, but the information transfer mechanism between sub-agents needs to be carefully designed.

A2 — Trigger Scenarios (Future Trigger) ★

In what situations would users need this skill?

1. Designing the toolset for an AI agent, defining tool interfaces from scratch
2. The number of tools has grown to the point where a discovery mechanism or grouping strategy is needed
3. Some tool operations involve security risks and require designing permission controls
4. Need to implement a sub-agent or parallel execution architecture
5. Need to choose a tool definition format (JSON Schema / XML / TypeScript)

Language Signals

• "AI needs to call external tools/APIs"
• "There are too many tools, and the model often uses the wrong one"
• "Some operations require user confirmation before execution"
• "How to design the schema for function calling"
• "Need sub-agents to process in parallel"

Distinction from Adjacent Skills

• Difference from safety-guardrails : The permission gating in tool-specification is operation control at the tool level ("can this button be pressed"), while safety-guardrails is behavior constraint at the content level ("can this topic be discussed"). The two are complementary but do not overlap.
• Difference from persona-design : persona-design determines "who" the AI is, while tool-specification determines "what" the AI can do.

E — Executable Steps (Execution)

1. Step 1: Choose the Definition Format

   • Evaluate the tool usage scenarios: use JSON Schema for standard API calls, use XML format when integration with the XML ecosystem is needed, and use TypeScript types for internal tools
   • Write an interface definition for each tool, including name, description, parameter list, and return value format
   • Completion criteria: The format choice has a clear rationale, and each tool's definition can be accurately understood and invoked by the model

2. Step 2: Implement Three-Layer Permission Gating

   • Classify all tool operations: Prohibited (automatically rejected), Explicit Permission (requires confirmation), Regular (automatically executed)
   • Design the user confirmation flow and timeout mechanism for the Explicit Permission layer
   • Completion criteria: Every tool operation has a clear permission-level classification, and the classification results have undergone security review

3. Step 3: Design the Discovery and Grouping Strategy

   • Number of tools <10: list all of them in the system prompt
   • Number of tools 10-25: group by functional domain, using namespaces
   • Number of tools >25: Implement a lazy loading mechanism (e.g., ToolSearch), discover on demand
   • Completion criteria: The model can find and invoke the correct tool within 2 rounds of dialogue in any scenario

4. Step 4: Design parallel execution and delegation mechanisms

   • Identify tool calls that can be parallelized (e.g., multiple independent searches, multi-file reads)
   • Design the sub-agent delegation protocol: task description format, result return format, error handling
   • Completion criteria: Parallel calls do not produce race conditions, and sub-agent results can be correctly aggregated by the main agent

5. Step 5: Define lifecycle and error handling

   • Design the lifecycle of tool calls: discovery → parameter construction → permission check → execution → result parsing → error recovery
   • Define a failure handling strategy for each stage
   • Completion criteria: Any tool call failure will not cause the agent to stall, and there is a clear degradation strategy

B — Boundary ★

Do not use this skill in the following situations

• The AI product does not need to call any external tools (pure conversation scenario)
• Tool integration is a backend engineering issue rather than a prompt design issue (e.g., API implementation)
• Attempting to solve security issues through tool design (security rules should be defined in safety-guardrails)
• The number of tools is very small (<5) and there are no security risks (a simple enumeration is sufficient, no complex design needed)

Common failure modes

• Ambiguous tool descriptions: The natural language description of the tool is not precise enough, causing the model to call the wrong tool in edge cases. Specific examples should be used instead of abstract descriptions.
• Over-simplified permission tiers: All operations are set to Regular or all require confirmation; the former leads to security risks, and the latter leads to a user experience disaster. The three-tier classification should be strictly used.
• Ignoring tool discovery cost: A large number of tools are all written into the system prompt, consuming valuable context window space. They should be loaded on demand.
• Sub-agent information silos: Sub-agents cannot share context with each other, leading to duplicated work or contradictory information. A clear information transfer protocol should be designed.
• Lack of error recovery: After a tool call fails, the agent directly gives up or falls into a retry loop. A degradation strategy and maximum retry count should be defined.