MCP Tool Annotations

Connect an MCP server to an agent and every tool arrives looking identical. list_contacts and delete_contact carry no risk signal at all, so approval policy collapses to all-or-nothing: force-approve every call and the guardrail is theatre, or block all writes and the agent can’t act. StackOne now emits standard MCP tool annotations on every tool we expose, derived from a new effects field on each action. Agents like Claude, ChatGPT Enterprise, Glean, and Copilot can use those hints to decide what runs unattended and what needs a human.

What’s new

• effects on every action - each action declares read, write, delete, search, or execute.
• Annotations derived automatically - readOnlyHint, destructiveHint, openWorldHint, and title are computed from effects at registration, so you don’t hand-author four flags per tool.
• Catalog-wide coverage - backfilled across the connector catalog rather than shipped connector-by-connector, so approval policy works the same everywhere.
• Escape hatch for edge cases - set raw MCP hints directly on an action when a single effect can’t express it.

How the hints are derived

- actionId: list_tickets
  effects:
    - read          # readOnlyHint: true
- actionId: create_ticket
  effects:
    - write         # readOnlyHint: false, destructiveHint: false
- actionId: delete_issue
  effects:
    - delete        # destructiveHint: true
- actionId: run_query
  effects:
    - execute
  annotations:
    idempotentHint: true   # explicit override, merged last

readOnlyHint is true when every effect is read or search. destructiveHint is true when any effect is delete. openWorldHint is always true, since these actions call external provider APIs.

Authoring effects on your own connectors is covered in the connector YAML reference.

Things to know

• idempotentHint is never inferred. HTTP method is a poor proxy once multi-step actions and dispatch are involved, so it can be set explicitly via the annotations override.
• Annotations are hints, not enforcement. Per the MCP spec, clients use them for approval defaults and grouping, not as a security boundary.