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

Annotations only say this is a non-read, non-destructive, open-world call; the description adds what they cannot: a hard cost of 2 AI credits from the monthly pool, that the org's own AI key is never used, that nothing runs or is charged without confirm: true, and what the unconfirmed call returns (the quote). That is exactly the behavioral context a cost-incurring mutation needs.

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?

Purpose is front-loaded in the first two sentences, and the remaining sentences are load-bearing instructions rather than filler. It is long and repeats the 'nothing runs and nothing is charged' point already in the confirm schema description, which is the only waste.

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 still tells the agent what an unconfirmed call yields (the quote), what a confirmed call does, how credits are drawn, and how approval scope works. For a 6-parameter, credit-spending tool that is complete.

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 67% and the schema already documents confirm, workspaceId, and idempotencyKey in detail. The description reinforces confirm's semantics (only after a clear yes) but adds no meaning for text, platform, or language beyond the schema. Baseline 3 is appropriate.

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+resource+scope: rewrite existing text into a target network's native style and length, with the '(a LinkedIn post is not an X post)' parenthetical pinning down what 'native style' means. It implicitly separates itself from write_caption (new text) and translate_caption (language change), but never names a sibling to route the agent explicitly, which keeps it at 4.

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?

Unusually explicit: call first without confirm to get a quote, tell the user in your own words what will run and what it costs, wait for a clear yes, then repeat with the same arguments and confirm: true. It also defines the boundary of a single approval ('one yes covers the plan they approved; anything new or different needs a new yes'), leaving no inference required.

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