MCP Tool Schema: Annotations

[Mookse]

Add MCP annotations to canonical tool JSON schemas

Summary

Each tool definition in inc/json-schemas/functions/ should include an annotations block per the MCP 2025-03-26 spec. These are optional behavioral hints consumed by MCP hosts/clients and ignored by non-MCP adaptors (e.g. OpenAI).

Annotation fields

Field	Type	Description
title	string	Human-readable display name
readOnlyHint	boolean	Tool does not modify state
destructiveHint	boolean	Tool may cause irreversible side effects
idempotentHint	boolean	Multiple identical calls = same result as one
openWorldHint	boolean	Tool may interact with external systems

Example

"annotations": {
  "title": "Delete Item",
  "readOnlyHint": false,
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false
}

Acceptance Criteria

• All tool JSON files in inc/json-schemas/functions/ include an annotations block
• MCP adaptor passes annotations through to MCP tool definitions
• OpenAI adaptor strips annotations before constructing function payload (to avoid API errors)
• mLoadTools requires no changes — loads canonical form as-is

Notes

• readOnlyHint candidates: getAction, getGeography, getPoliticalLeaning, getStance, getSummary, getValue, getValuesBackground, itemSummary
• destructiveHint candidates: any delete or obscure operations
• openWorldHint candidates: callAvatar, callExternalAgent (cross-system calls)