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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns perfectly. It adds rich behavioral context: while running returns status/progress without content, completed response includes files+manifest, failed response includes failure reason. This goes well beyond annotations and prepares the agent for all response variants.

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 somewhat lengthy but every sentence earns its place: purpose, behavior, response types, filtering. It is front-loaded with the main action and progressively adds detail. No fluff, but it could be tightened slightly without losing value.

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 the tool's complexity (polling, async job states), the description is remarkably complete. It explains the full lifecycle, what to expect at each status, the manifest, and the filtering option. Combined with the output schema (present), an agent has everything needed to invoke and interpret results correctly.

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 covers both parameters at 100%, so baseline is 3. The description adds value by explaining why targetLanguages is useful ('bound the payload of a large job') and by reinforcing that jobId comes from translate_files. It doesn't introduce new syntax but clarifies intent.

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 ('poll', 'pull back'), a clear resource (translation job started by translate_files), and differentiates from sibling translate_files by describing the retrieval/polling role. The agent immediately understands what this tool does and how it fits into the workflow.

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?

Explicitly says when to use it (after translate_files starts a job) and describes the polling loop ('call again until status is completed'). It also mentions the optional filter to bound payload, giving clear guidance on when that parameter is useful. No ambiguity about alternatives.

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