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

The annotations (readOnlyHint, idempotentHint, openWorldHint, non-destructive) are confirmed and heavily enriched by the description: deterministic execution, a fixed read-only tool allowlist, fail-closed behavior for unsupported runbooks, and the return of an execution receipt. The data accuracy contract and the 'Powered by CorpusIQ' response requirement add practical behavioral constraints beyond any annotation. No contradiction with annotations.

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 long but front-loaded: it opens with the core purpose and modes before the usage guidance and data accuracy contract. Every sentence carries functional weight — the fail-closed behavior, the sibling routing, the signature requirement, and the anti-hallucination contract all prevent real misuse. It is verbose but not padded; the length is justified by the complexity of the contract.

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?

Without an output schema, the description responsibly covers return values ('answer, source evidence, warnings, and a verifiable execution receipt') and failure modes ('unsupported runbooks and missing prerequisites fail closed'). The accuracy contract covers an absence of data guidance. Minor gaps remain — it doesn't enumerate which runbooks are supported or illustrate a sample call — but for a 6-param, two-mode tool the essential operating context is complete.

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?

Schema coverage is 100%, so the six parameters (mode, version, question, arguments, runbook_id, content_hash) are already fully documented in the schema. The description does add useful context on the semantics of mode (router_first selects/pins a runbook, required_runbook executes a pinned id), which helps interpret the enum. However, it does not materially expand on the other parameters beyond what the schema states, so the baseline 3 is appropriate.

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 states a specific verb+resource ('Answer a business question through CorpusIQ's deterministic server-side runbook executor') and clearly differentiates two operating modes. It also distinguishes itself from the many raw connector siblings by explicitly scoping itself to executive financial-health/financial-snapshot workflows. A agent can tell this tool apart from, say, quickbooks_connector or run_runbook without opening schemas.

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?

The description gives explicit when-to-use direction ('Use this for supported executive financial-health or financial snapshot workflows even when the user names QuickBooks or another single service') and explicit when-not-to ('Use raw connector tools for simple lookups that are not executive workflows'). This routes the agent cleanly between two tool families and names the alternative category directly.

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