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

Goes well beyond the annotations: it discloses that nothing is listed and no score exists until a maintainer verifies terms, and it spells out concrete idempotency behavior (already-listed domain returns its listingUrl; already-queued domain returns the existing submission). Annotations give idempotentHint=true, and this description makes that hint actionable rather than just declarative.

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?

Front-loaded with the trigger condition, then dedup behavior, then URL constraint, then next step. No sentence is redundant despite the density.

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?

Covers the trigger, the async/manual verification model, duplicate handling, source-quality rules, and the follow-up tool. An output schema exists and the description still names the returned id used for status polling, so nothing an agent needs is missing.

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%, so the baseline is 3, but the description adds a real constraint beyond the schema by restricting programUrl sourcing to the brand's own program or partners page and forbidding invented terms. Other parameters (note, contact, termsUrl, name) are left to the schema, which handles them adequately.

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?

Specific verb (queues for verification) plus resource (the brand's own affiliate program page) and an explicit statement of what the tool is not for. An agent can distinguish it from get_program and search_programs without opening either 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?

Names the precondition explicitly ("Use when get_program and search_programs do not find a brand's affiliate program"), adds a hard exclusion on what URL to send (never a network or review site), and prescribes the follow-up call to get_submission_status.

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