Designing tool contracts

Prefer verb-and-object names such as get_weather_forecast, list_calendar_events, and create_calendar_event. A concrete name helps the model map user intent to capability. It also helps developers, reviewers, and logs communicate what was proposed.

Avoid names such as execute, helper, api_call, or manage_account. They group unrelated behavior behind one label. A broad manage_account tool might read a profile, change an address, close an account, or reset a password. Those actions need different arguments and permissions. Split them so policy can allow reading while requiring approval for closing.

Names should be stable implementation-facing identifiers, not marketing copy. Use a predictable style and avoid near-duplicates such as find_weather, lookup_weather, and weather_search unless their scopes truly differ. Too many overlapping tools make selection harder and evaluation less interpretable.

A tool description should say what the tool does, when to use it, and important limits. It should not simply repeat the name. Compare:

• Weak: “Gets weather.”
• Better: “Returns observed conditions or a forecast for one supported location and date up to five days ahead. Does not provide climate averages or historical records.”

The better description gives the model positive and negative decision guidance. For a calendar write, include whether the tool creates immediately, whether attendees receive invitations, and whether a prior user confirmation is required. The model can then distinguish drafting event details from causing a side effect.

Descriptions are not security controls. A sentence saying “administrators only” can guide selection, but the application still has to check the authenticated user’s role. The model can misunderstand text or receive hostile instructions. Enforce boundaries outside the model.

A schema defines allowed fields, types, required values, formats, and often enumerations. Here is a simplified creation contract:

{
  "name": "create_calendar_event",
  "description": "Creates one event after the user confirms the final details.",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["title", "starts_at", "ends_at", "timezone"],
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 120
      },
      "starts_at": {
        "type": "string",
        "format": "date-time"
      },
      "ends_at": {
        "type": "string",
        "format": "date-time"
      },
      "timezone": {
        "type": "string",
        "description": "IANA timezone, such as Asia/Dubai"
      },
      "visibility": {
        "type": "string",
        "enum": ["default", "private"]
      }
    }
  }
}

Types convert vague prose into checkable claims. starts_at cannot be “after lunch sometime” if the implementation needs an exact timestamp. An enum prevents invented visibility modes. additionalProperties: false rejects unexpected fields instead of silently accepting a model-invented option.

Schema validation is necessary but not sufficient. A string may match the date-time format while representing an end before the start. The application must perform semantic validation too.

Require only what execution truly needs. If every field is required, the model may fill missing information with guesses. If too few are required, invalid calls travel farther into the system.

Optional fields should have clear behavior when absent. Does an omitted attendee list mean “invite nobody,” “use the current user,” or “ask a question”? Defaults belong in the application contract, not in hidden assumptions. Document them and use conservative defaults for side effects.

Some values should not come from the model at all. The authenticated user ID, OAuth token, billing account, tenant ID, permission scope, and audit actor should be derived from trusted application state. A model-generated argument such as "user_role": "admin" is untrusted data, not authorization.

Separate user-facing references from provider identifiers. The user may say “my design calendar,” while the application resolves that phrase to an allowed calendar ID. Do not let the model submit an arbitrary account identifier that bypasses tenant boundaries.

The tool result is another contract. Return enough structured information for the model to explain what happened without exposing secrets or dumping an entire provider response.

{
  "status": "created",
  "event_id": "evt_8421",
  "title": "Design review",
  "starts_at": "2026-07-21T10:00:00+04:00",
  "ends_at": "2026-07-21T10:30:00+04:00",
  "invite_status": "not_sent"
}

This result distinguishes event creation from invitation delivery. That prevents the assistant from saying “Everyone has been invited” when the tool only saved a private event. Return stable error codes as well as human-readable details so the application can decide whether to retry, clarify, or stop.

Never return access tokens, raw credentials, internal stack traces, or unrelated personal data to the model. Minimize results to the information needed for the current task.

Tool contracts become dependencies. Renaming fields, changing defaults, or broadening behavior can break prompts, eval cases, logs, and downstream code. Version a tool when behavior changes incompatibly, or support a migration window.

Test contracts with ordinary requests, missing details, contradictory dates, unsupported values, and adversarial arguments. Ask whether two tools overlap, whether descriptions expose a reliable decision boundary, and whether each result proves exactly what the assistant may claim.

A narrow, boring tool is often better than a magical one. Deterministic code can compose small capabilities safely, while an all-purpose tool hides side effects and makes failures difficult to locate.