Translate a caption

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

Annotations already declare readOnlyHint=true, so the agent knows nothing is mutated; 'Drafts only' is consistent with that and reinforces it. The description adds genuine behavioral detail by stating that the hook, @mentions, #hashtags and links are preserved in translation, but it says nothing about failure handling for invalid or unsupported language codes.

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?

Two short sentences, both load-bearing: the first states the operation and its preservation guarantees, the second states the non-publishing boundary. Nothing is redundant or buried.

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?

With no output schema, the description should indicate what comes back — for example, a draft per requested language or a single combined result. That return-shape gap and the undocumented caption parameter leave an agent guessing about the response despite the tool otherwise being simple.

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 only 50%: the languages array is documented with BCP-47 guidance and bounds, but the caption parameter has no description. The description implicitly clarifies the roles (caption is the source text, languages are targets), which partially compensates, but it adds no detail about caption format or length constraints.

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 gives a specific verb (drafts a translation) and resource (caption), and adds scope with 'Drafts only', so an agent knows this produces text rather than publishing. It stops short of naming the adjacent sibling generate_caption, so the boundary between 'write a caption' and 'translate a caption' must be inferred from the name alone.

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?

'Drafts only' implies this is a pre-publish step rather than a publishing action, which is useful context. However, there is no explicit guidance on when to pick this over generate_caption, or whether the draft must then be passed to publish_photo/publish_reel.

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