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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the call is never charged, rate limits apply, auth requires a vq_key_ with translate:read, and pagesCharged stays null until completion. That is solid added value, though it does not cover pagination or latency behavior.

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 purpose and the free/polling note are front-loaded, and the status table plus error section are scannable and each earn their place. The verbose curl example partially duplicates the authentication and URL information already stated, adding modest redundancy.

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?

An output schema exists, so return-value explanation is optional, yet the description goes further by enumerating status values, progress semantics and error codes. The one substantive gap is that it never explains where the required document id comes from or which sibling tool produces it.

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 single parameter 'id' has 0% schema description coverage, leaving the description responsible for explaining it. The only hint is '$DOCUMENT_ID' inside a curl example; it never says the id is the value returned by create_document or upload_file, nor what format it takes, so an agent must infer the parameter's origin.

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 opening line states a specific verb and resource: retrieving the status of a document translation job, which is narrower and clearer than the bare name 'get_document'. It distinguishes itself from content retrieval only indirectly by pointing at '/content' as the download path rather than naming the sibling tool get_document_content.

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?

It gives concrete usage context: poll this endpoint, at a 2-5 second cadence, and it is free so polling is unlimited within rate limits. What's missing is an explicit handoff statement such as 'once status is completed, call get_document_content to download' — the routing hint is given as a raw HTTP path instead of a sibling tool name.

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