skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
eyadsibai/ltk63 installs

tool-design

Use when designing agent tools, creating tool descriptions, implementing MCP tools, or asking about "tool design", "agent tools", "tool descriptions", "MCP", "function calling", "tool consolidation"

How do I install this agent skill?

npx skills add https://github.com/eyadsibai/ltk --skill tool-design
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides educational guidelines and architectural best practices for designing agent tools, descriptions, and function calling conventions. No security risks or malicious patterns were detected.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerpass

    1 file scanned · No issues

What does this agent skill do?

Tool Design for Agents

Tools define the contract between deterministic systems and non-deterministic agents. Poor tool design creates failure modes that no amount of prompt engineering can fix.

The Consolidation Principle

If a human engineer cannot definitively say which tool should be used, an agent cannot do better.

Instead of: list_users, list_events, create_event Use: schedule_event (finds availability and schedules)

Tool Description Structure

Answer four questions:

  1. What does the tool do?
  2. When should it be used?
  3. What inputs does it accept?
  4. What does it return?

Well-Designed Tool Example

def get_customer(customer_id: str, format: str = "concise"):
    """
    Retrieve customer information by ID.

    Use when:
    - User asks about specific customer details
    - Need customer context for decision-making
    - Verifying customer identity

    Args:
        customer_id: Format "CUST-######" (e.g., "CUST-000001")
        format: "concise" for key fields, "detailed" for complete record

    Returns:
        Customer object with requested fields

    Errors:
        NOT_FOUND: Customer ID not found
        INVALID_FORMAT: ID must match CUST-###### pattern
    """

Poor Tool Design (Anti-pattern)

def search(query):
    """Search the database."""
    pass

Problems: Vague name, missing parameters, no return description, no usage context, no error handling.

Architectural Reduction

Production evidence shows: fewer, primitive tools can outperform sophisticated multi-tool architectures.

File System Agent Pattern: Provide direct file system access instead of custom tools. Agent uses grep, cat, find to explore. Works because file systems are well-understood abstractions.

When reduction works:

  • Data layer well-documented
  • Model has sufficient reasoning
  • Specialized tools were constraining
  • Spending more time maintaining scaffolding than improving

MCP Tool Naming

Always use fully qualified names:

# Correct
"Use the BigQuery:bigquery_schema tool..."

# Incorrect (may fail)
"Use the bigquery_schema tool..."

Response Format Optimization

format: str = "concise"  # "concise" | "detailed"

Let agents control verbosity. Concise for confirmations, detailed when full context needed.

Error Message Design

Design for agent recovery:

{
    "error": "NOT_FOUND",
    "message": "Customer CUST-000001 not found",
    "suggestion": "Verify customer ID format (CUST-######)"
}

Tool Collection Guidelines

  • 10-20 tools for most applications
  • Use namespacing for larger collections
  • Ensure each tool has unambiguous purpose
  • Test with actual agent interactions

Anti-Patterns

  • Vague descriptions: "Search the database"
  • Cryptic parameters: x, val, param1
  • Missing error handling: Generic errors
  • Inconsistent naming: id vs identifier vs customer_id

Best Practices

  1. Write descriptions answering what, when, returns
  2. Use consolidation to reduce ambiguity
  3. Implement response format options
  4. Design error messages for recovery
  5. Establish consistent naming conventions
  6. Test with actual agent interactions
  7. Question if tools enable or constrain reasoning
  8. Build minimal architectures for model improvements

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/eyadsibai/ltk/tool-design">View tool-design on skillZs</a>