Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that this broker never produces an unaudited side effect, returns only a fixed set of outcomes (needs_user_input, needs_approval, pending_approval, executed, denied, unsupported), and requires idempotency_key for mutations and human authority for high-risk changes. The annotations say destructiveHint=true and idempotentHint=true, which align with the description — no contradiction. The description adds meaningful operational context that the annotations alone do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: scope, supported intents, sibling alternatives, required keys, authority requirement, and return outcomes. The alternative tool routing is front-loaded, and the behavioral guarantees are stated compactly at the end. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (12 params, nested objects, multiple intents, mutation semantics), the description covers the critical behavioral contract: return values, idempotency, authority, and routing to alternatives. The output schema exists and the input schema is fully documented, so the description need not repeat those details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% parameter coverage, so the baseline is 3. The description adds value by specifying which intents map to which payload fields (E911 requires address + disclosure_acknowledged=true; transcripts requires webhook_url + events), which helps an agent construct the payload correctly without relying solely on the schema's generic wording.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a governed mutation broker for specific intents, listing exact intent values and naming the sibling tools it should not be used for. This distinguishes it from the many update/configure siblings without needing to inspect each schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly lists preferred alternatives for several use cases (update_agent_config for prompt/voice/model edits, configure_agent_business_rules for a single named operational prompt section, upsert_lead for lead create/update, send_sms for outbound texts, configure_staff_alerts for alert recipients/rules, configure_textable_links for send-link setup). This gives the agent clear routing guidance beyond what the schema alone provides.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.