tool-design

🛠️ Tool Design for Agent Systems

This skill provides the principles for designing interfaces that AI agents can discover, understand, and use with high fidelity. Unlike traditional APIs for humans, agent tools must prioritize semantic disambiguation, atomic composition, and token efficiency in observations.

Mental Model: A tool is an extension of the model's reasoning. If a human engineer cannot clearly distinguish when to use Tool A vs Tool B, the agent will not be able to either. Descriptive clarity outweighs technical sophistication.

🚩 Fragility and Autonomy

• Fragility: Medium. A poor tool description can lead to infinite call loops or hallucinated arguments.
• Freedom: High in the technical implementation of the tool logic, but Low in the structure of its definition.

🚀 When to Activate

• When building new capabilities for an agent (MCP, Plugins).
• To debug recurring failures in tool calls (Tool-Call Failures).
• When noticing that the agent gets confused between multiple similar tools.
• To optimize token usage in tool outputs.

🧠 Core Concepts

1. The Consolidation Principle

Avoid the proliferation of small tools. Prefer richer tools with optional parameters that group related workflows.

• Example: Instead of list_users, get_user_email and update_user_role, create a tool manage_user that handles the user lifecycle.

2. Architectural Reduction

As the model (e.g., Gemini 3 Ultra) improves its reasoning, eliminate specialized tools in favor of powerful "primitives."

• Pattern: Replace 10 data exploration tools with a single execute_command that allows the agent to use grep, find and ls directly on the file system.

3. Tool Description Engineering

An effective description answers:

1. What does it do?: Specific and direct action.
2. When to use it?: Clear triggers and indirect signals.
3. What does it accept?: Parameters with types, constraints, and default values.
4. What does it return?: Output format and possible errors.

🛠️ Implementation in Gemini Elite Core

Pattern: Response Format Selection

Allows the agent to choose the verbosity of the response to save tokens.

{
  "name": "get_customer",
  "parameters": {
    "format": "concise | detailed",
    "description": "concise: solo id y status; detailed: registro completo."
  }
}

Pattern: Error-as-Guidance

Errors should not be terminal; they should be recovery instructions.

{
  "error": "INVALID_ID",
  "message": "El ID debe empezar por 'CUST-'. Ejemplo: 'CUST-0001'.",
  "resolution": "Verifica el ID del cliente e intenta de nuevo."
}

---

🔗 Integrations

• context-fundamentals: Relationship between tool definitions and attention budget.
• evaluation: Tests of effectiveness and fidelity of tool calls.
• filesystem-context: Use of primitive filesystem tools.

📚 Internal References

• references/best_practices.md: Guide to naming conventions, parameter types, and concrete examples.
• references/architectural_reduction.md: Case study on how eliminating 80% of tools improved task success.