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

No annotations are provided, so the description carries the full transparency burden. It discloses the GET method, the endpoint format, the response structure, the localized path_tr field, the idle cost ('Idle $0'), and boundary conditions ('No DID sales / no live PSTN'). It does not cover authentication, rate limits, or error behavior, but it provides substantially more behavioral context than a generic read-tool description.

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 short and front-loads the main concept, which is good. But the phrase 'Idle $0.' appears twice, and marketing language like 'moat' and 'compounding asset' adds noise without helping an agent act. It is concise but not perfectly economical.

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?

For a two-parameter read tool with no output schema, the description supplies essential context: the HTTP method, query parameters, the names of returned fields, the plain-Turkish variant, and the search/orchestration use case. It does not deeply define what path or edges mean semantically, but the 'who→whom→where' framing covers the core meaning well enough.

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 100%, and both call_id and stuck_at already have meaningful schema descriptions. The description only restates them in endpoint shorthand ('call_id=…&stuck_at=310') without adding new semantic detail. Baseline 3 is appropriate because the schema does the heavy lifting.

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 names a concrete resource ('Handoff graph + transfer edges') and explicitly states the HTTP endpoint and return fields ('Returns path, path_tr, edges, and raw transfers'). It also distinguishes itself from transcript-style tools by saying 'handoff edges, not a bot transcript,' which helps an agent separate it from siblings like pbx_calls or pbx_search. The 'moat' jargon is decorative, but the core purpose is unmistakable.

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 a clear use context: 'Compounding asset for search/orchestration' and explicitly contrasts with 'not a bot transcript.' That conveys when to reach for this tool versus a transcript-oriented tool. However, it never names specific sibling tools or states when NOT to use it in favor of pbx_calls_get or pbx_search, so the guidance is contextual rather than fully explicit.

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