Sign in Subscribe

Tool Engineering

Tool Engineering

Skill 8: Semantic Capability and Tool Engineering

The interface design discipline for the age of agents.

Overview

Skill 8 represents the critical discipline of designing, building, and managing the tools that agents use to interact with the world. Agents extend their capabilities through tools—functions, APIs, and services that allow them to perform actions beyond language generation. The quality of these tools is a primary determinant of agent performance.

This skill addresses the art and science of creating tools that are discoverable (agents can find them), understandable (agents know when and how to use them), and safe (agents can use them without causing harm).

The Four Sub-Skills

Sub-Skill Focus Area Key Concepts
8.1 Function Calling Designing clear schemas and error handling JSON Schema, OpenAPI, structured errors
8.2 Tool Discovery Enabling agents to find and chain tools Tool registries, semantic search, composition
8.3 Tool UX Design Crafting descriptions for semantic usability Clear descriptions, examples, semantic altitude
8.4 Agent Skills Standard Modular, scalable tool packaging Progressive disclosure, SKILL.md format

8.1 Function Calling and Tool Definitions

Designing Clear Tool Schemas

  • Core Principle: Every tool must have a precise schema defining inputs, outputs, and behavior
  • Format: JSON Schema or OpenAPI specification
  • Requirements: Descriptive names, parameter descriptions, type constraints, required fields

Implementing Robust Error Handling

Structured Error Response:

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'location' is missing",
    "suggestion": "Provide a city name, e.g., 'San Francisco'"
  }
}

Function Calling Protocols

  • OpenAI: tools parameter, returns tool_calls
  • Anthropic: tools parameter, returns tool_use blocks
  • Google: function_declarations, returns function_call

8.2 Dynamic Tool Discovery and Composition

Tool Registries and Catalogs

  • Purpose: Searchable catalog of available tools
  • Metadata: Name, description, category, tags, version, usage stats
  • Implementation: Database with search APIs, filtering by category and semantic similarity

Semantic Search for Tools

  • Approach: Embedding-based search with natural language queries
  • Tools: OpenAI embeddings, sentence transformers
  • Storage: Vector databases (Pinecone, Weaviate, Qdrant)

Tool Composition and Chaining

Design Patterns:

  • Pipeline: Sequential tool execution
  • Fan-out/Fan-in: Parallel execution with result aggregation
  • Conditional: Tool selection based on intermediate results

8.3 Tool UX Design for Agents

Writing Clear Descriptions

A good tool description includes:

  • What: What does the tool do?
  • When: When should the agent use it?
  • Inputs: Parameter meanings and formats
  • Outputs: Return value format and structure
  • Constraints: Limitations and requirements

Providing Tool Examples

Example 1: Get weather in Celsius
Input: {"location": "Tokyo", "unit": "celsius"}
Output: {"temperature": 18, "conditions": "Partly cloudy"}

Example 2: Get weather in Fahrenheit
Input: {"location": "New York", "unit": "fahrenheit"}
Output: {"temperature": 72, "conditions": "Sunny"}

Optimizing Semantic Altitude

  • Low Altitude (too specific): "Get weather in San Francisco in Fahrenheit"
  • Optimal: "Get current weather for any location in specified units"
  • High Altitude (too general): "Get information about something"

8.4 Agent Skills Standard

Progressive Disclosure

  • Problem: Loading all tool documentation exhausts context window
  • Solution: Initially show only skill names and brief descriptions
  • On-demand: Load full documentation only when skill is deemed relevant

Directory Structure

skills/
  weather/
    SKILL.md          # Interface (always loaded)
    detailed_docs.md  # Loaded on demand
    schema.json       # Loaded on demand
    examples/         # Loaded on demand

Transferable Competencies

Mastering Skill 8 requires proficiency in:

  • API Design: RESTful design, OpenAPI, JSON Schema
  • Interface Design: Usability principles, documentation, examples
  • Semantic Engineering: Natural language understanding, embeddings
  • Software Engineering: Modularity, composability, error handling
  • Information Architecture: Categorization, tagging, metadata design

Common Pitfalls

  1. Ambiguous schemas: Vague parameter descriptions lead to agent errors
  2. Poor error messages: Cryptic errors prevent agent self-correction
  3. No examples: Agents struggle to learn tool usage without examples
  4. Wrong semantic altitude: Too specific or too general descriptions
  5. No tool discovery: Hardcoded tool lists don't scale
  6. Non-composable tools: Incompatible formats prevent chaining
  7. Context overload: Loading all documentation upfront wastes context
  8. No versioning: Breaking changes break existing agents

Key Technologies

Function Calling Platforms

  • OpenAI, Anthropic, Google function calling

Schema Standards

  • JSON Schema (data structure definition)
  • OpenAPI (API specification)
  • OASF (Open Agentic Schema Framework)

Tool Standards

  • Anthropic Agent Skills (modular packaging)
  • MCP (Model Context Protocol)

Search and Discovery

  • Embedding Models (OpenAI, sentence transformers)
  • Vector Databases (Pinecone, Weaviate, Qdrant, Chroma)

The Bottom Line

Skill 8 is the interface design discipline for the age of agents. Tools are not just APIs—they are the user interface through which agents interact with the world. By applying rigorous engineering principles to tool design, organizations can build rich ecosystems of discoverable, understandable, and composable capabilities.

← Back to Nine Skills Framework | Next: Skill 9 - Security & Resilience →