Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

7.3 KB
Raw Blame

Guide to Writing AI Tools

This guide covers best practices for designing tools that AI agents can use effectively. Tools are a contract between deterministic systems and non-deterministic agents—they require fundamentally different design thinking than traditional APIs.

Core Philosophy

Tools should be designed around how agents think, not how your backend is organized. An agent doesn't care about your microservice boundaries or database schema. It cares about accomplishing tasks with minimal friction and context waste.

The goal: Enable an agent to accomplish tasks as efficiently as a knowledgeable human team member would.

Tool Design Principles

1. Tools Are Not Endpoints

Do not create a 1:1 mapping between API endpoints and tools. This is the most common mistake.

Instead, design tools around workflows and intentions. A single tool might orchestrate multiple backend calls, or conversely, a single complex endpoint might become several focused tools.

Think workflow, not API: If a human would naturally perform several operations together to accomplish a goal, that's probably one tool. If a single endpoint serves multiple distinct purposes, that's probably multiple tools.

2. Curate, Don't Expose

Tools should expose a curated selection of capabilities, not a comprehensive API surface. More tools don't guarantee better outcomes—they create confusion. Every tool you add competes for the agent's attention and increases the chance of suboptimal tool selection.

Ask yourself:

  • Does this tool serve a clear, distinct purpose?
  • Would an agent naturally reach for this when given a relevant task?
  • Is this tool's purpose obviously different from existing tools?

3. Simplify Parameters

Complex endpoints with many options should become either:

  • Multiple simple tools with focused purposes, OR
  • One tool with simplified, opinionated options

Agents work best with clear, constrained choices. A tool with 15 optional parameters forces the agent to reason about combinations it may not understand. A tool with 2-3 well-chosen parameters guides the agent toward success.

Prefer enums over strings: When a parameter has known valid values, use an enum. This eliminates hallucination risk and makes the tool self-documenting.

4. Filters Over Pagination

List endpoints should never expose pagination parameters to AI. Pagination is an implementation detail that agents handle poorly—they don't know when to stop paging, waste context on partial results, and often miss relevant items.

Instead, provide semantic filters that let agents request exactly what they need:

  • Filter by status, type, date range, ownership
  • Support search/query parameters for text matching
  • Return reasonably-sized result sets with sensible defaults

If results might be large, implement truncation with a summary (e.g., "showing 50 of 234 results matching your criteria").

5. Return What's Needed, Not Everything

Tool responses should contain high-signal, contextually relevant information. Returning comprehensive technical details wastes the agent's limited context window.

Consider implementing a response_format parameter with options like "concise" or "detailed" when tools might return varying levels of detail. The concise format for reasoning, the detailed format when the agent needs specific identifiers for downstream operations.

Naming and Documentation

Tool Names

Names should be:

  • Unambiguous: The purpose should be clear from the name alone
  • Action-oriented: Use verbs that describe the workflow (search_customers, schedule_meeting)
  • Namespaced when related: Group related tools with prefixes (documents_search, documents_create)

Descriptions

Tool descriptions are prompt engineering. Write them as you would explain the tool to a new team member:

  • State the tool's purpose in one sentence
  • Explain when to use it (and when not to)
  • Make implicit context explicit (expected formats, terminology, relationships between concepts)
  • Describe what the tool returns

Parameter Descriptions

Every parameter needs a clear description. Avoid ambiguous names—use user_id not user, project_name not project.

For the ai_toolset crate, use schemars attributes:

  • #[schemars(title = "...", description = "...")] on the input struct
  • #[schemars(description = "...")] on each field

See src/lib.rs for documentation patterns and src/schema/ for schema requirements.

Error Messages

Return specific, actionable error messages. "User not found" is better than "404". "No documents match the filter 'status=archived'" is better than "Empty result".

Agents use error messages to self-correct. Help them understand what went wrong and what to try instead.

Consolidation Patterns

Look for opportunities to combine related operations into workflow-oriented tools:

Instead of: list_users, list_events, check_availability, create_event Consider: schedule_meeting (finds availability and creates the event)

Instead of: get_customer, list_transactions, list_notes Consider: get_customer_context (compiles relevant recent information)

Instead of: read_file with line numbers Consider: search_file_content (returns relevant sections with context)

The goal is reducing the number of tool calls needed for common tasks while keeping each tool's purpose clear.

Testing Tools

Create evaluations using realistic, multi-step tasks. Analyze agent reasoning to identify:

  • Tools the agent avoids or misuses
  • Parameters that cause confusion
  • Missing capabilities that force awkward workarounds
  • Excessive tool calls that could be consolidated

Iterate on tool design based on how agents actually use them, not how you imagine they will.

Summary Checklist

Before adding a tool, verify:

  • The tool serves a clear, distinct workflow purpose
  • It's not a 1:1 endpoint mapping
  • Parameters are simple and well-constrained
  • No pagination—uses filters instead
  • Returns appropriately-sized, relevant responses
  • Name clearly conveys purpose
  • Description explains when and how to use it
  • All parameters have clear descriptions
  • Error messages are actionable

Further Reading

Telemetry

Every tool call dispatched through ToolSet::try_tool_call runs inside an OpenTelemetry GenAI execute_tool span (see ai_toolset::telemetry). The span carries the tool name, the arguments as input and the result as output — the attributes an LLM-as-a-judge evaluation of tool selection reads — and an error status when the call fails. Two rules follow:

  • Tools and toolsets do not open tool telemetry themselves. Implement ToolSet::dispatch_tool_call (routing only) and let try_tool_call wrap it; a toolset that delegates to children calls their dispatch_tool_call, so one call yields exactly one tool span. Inside a tool, ordinary #[tracing::instrument] spans for its own work are fine and nest under it.
  • Arguments and results are content, recorded under the content policy (OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, on unless set to false) and cut to a size budget. Do not record them as span fields or log them in tools: that bypasses the policy and repeats them on every log line.