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

With no annotations provided, the description carries the full behavioral burden, and it delivers: it discloses rate limits (120/hour/key), shared bucket behavior, idle cost, PSTN constraints, cross-tenant isolation, and the fact that the tool records intent rather than executing live calls. This is far more transparent than the bare endpoint name.

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 packs in useful detail, but it is cluttered with redundant phrases ('Idle $0' appears twice), jargon ('E1 moat'), and repeated 'own PBX optional footnote' ideas. The key behavioral facts are present but not as cleanly organized as they could be.

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 there is no output schema and no annotations, the description provides a strong operational picture: endpoint, request shape, core behavior, rate limits, cost model, and runtime constraints. It does not describe the response format or authentication expectations, but it is otherwise reasonably complete for an invokable tool.

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 description coverage is only 50%, so the description needed to compensate. It does add meaning for the core inputs (promise_id and action) and mentions the suggested action set, but it leaves pbx_id, agent_ext, skip_forward, and stasis_webhook_url mostly unexplained. This is adequate for the main required parameter but incomplete across all six parameters.

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 states the tool's verb and resource: it loads a promise and call graph, suggests whisper/transfer/hold, and records orchestra intent for agent handoff. It is specific enough to distinguish from a generic promise tool, though it does not explicitly differentiate itself from closely related siblings like pbx_orchestra_act or pbx_whisper_suggest.

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?

Usage context is implied through the description: use it when a promise's call graph should be converted into orchestra handoff intent. It offers some constraints (no live PSTN, managed SaaS, no cross-tenant merge) but does not explicitly state when to prefer this tool over related siblings or list exclusions.

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