match speakers to faces

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

Goes well beyond the annotations: attempt accounting (max 3 including the automatic one, then retry_limit), that an in-flight or completed analysis is returned unchanged even with retry, that a new attempt overwrites a failed result, cost (free), rate limit (3/min), in-request execution time, timeout survival behavior, and the 409/422 failure conditions. These are consistent with destructiveHint=true and idempotentHint=false rather than in conflict with them.

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?

Front-loads purpose, then the routing rule, then constraints and failure modes; nearly every clause carries operational information. It is a single dense paragraph, though, and the rate-limit/cost/failure-code tail is packed tightly enough to be easy to skim past.

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 non-idempotent, potentially minutes-long, attempt-limited operation with no output schema, the description covers preconditions, alternatives, retry semantics, wait strategy, quotas, and error codes. Return shape is delegated to transcriptions_get-speaker-analysis, which is the correct move given no output schema.

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 baseline is 3, and the description adds real semantics on top: the attempt-limit consequences of 'retry', the staleness/409 meaning of 'revision', and the 422 refusal for a foreign 'sourceVideoUrl'. It largely echoes the schema's own error notes, so it is additive but not fully independent.

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?

States a specific verb and resource ('run, or retry, the speaker-to-face match') and an explicit precondition (a COMPLETED video transcription), then distinguishes itself from the sibling read tool by name. An agent can tell instantly that this initiates work rather than returning existing analysis.

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?

Gives explicit when-to-use criteria ('only when that read says unavailable with reason not_requested, or with retry: true after a failed or timed-out attempt'), names the alternative to consult first (transcriptions_get-speaker-analysis), and enumerates when not to call (audio-only, >2 minutes, >8 speakers) along with the recovery path after a timeout.

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