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

Annotations already cover the read-only/idempotent safety profile, and the description adds real value beyond them: expected latency, poll cadence, the result.pins payload shape, and the scope boundary against get_generation_status. It only gestures at 'status is success' without enumerating failure/pending states or what to do if polling runs long, which is the one behavioral gap.

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?

Four short sentences, each doing distinct work, with purpose front-loaded and the sibling disambiguation last. Nothing repeats the schema or the annotations.

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 annotations, a 100%-documented single parameter, and an output schema, the definition covers everything needed to call the tool correctly and act on the result. Only the non-success status handling is left implicit.

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% and the single jobId is fully documented as the ID returned by generate_pin_copy, so the schema carries the load. The description reinforces provenance but adds no new syntax or format information. Baseline 3 applies when the schema does the work.

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) and resource (a Pin copy generation started by generate_pin_copy), and explicitly rules out the confusingly similar get_generation_status used for generate_pins_from_url jobs. An agent can pick it apart from its siblings without opening any schema.

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 the exact trigger (after calling generate_pin_copy), the polling recipe (~every 5 seconds, typically under a minute), and two concrete next actions on success (offer to user, or pass one to create_post). It also names the alternative tool and the condition that selects it.

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