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

With annotations present the bar is lower, and the description does add value by declaring 'removes and submits nothing' and 'No confirm needed' — operational facts not encoded in any annotation. However it says nothing about what happens to already-paired items, whether the pairing is reversible, or what a call returns, and the openWorldHint=true / idempotentHint=false traits are left unexplored.

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?

Three compact clauses, front-loaded with the scope and action, and each clause carries information: scope, non-destructive behavior, usage condition, confirm behavior. Slightly clipped telegraphic style ('pre-pair') but no wasted sentences.

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?

For a two-parameter mutation-adjacent tool with no output schema, the description covers non-destructiveness and the no-confirm path, which are the key agent concerns. It is still missing the undocumented project_id, any prerequisites (e.g. listings must be imported first), and any hint of outcome, leaving noticeable gaps.

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%: marketplace_id is fully documented in-schema (with a pointer to list_marketplaces), but project_id has no description anywhere. The description never mentions project_id or what scoping it controls, so it fails to compensate for the coverage gap as required at low coverage.

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 and resource ('pre-pair — pair existing channel listings with the Koongo items') plus an explicit scope ('MARKETPLACE-wide'), which implicitly separates it from the ad-wide sibling pre_pair_ad_items. It does not name the sibling outright, so differentiation is by scope adjective rather than by direct contrast.

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?

States a clear selection condition: 'Use this when the channel already holds listings.' That is a real when-to-use rule an agent can apply. It stops short of naming the alternative (pre_pair_ad_items) or describing what to do when the channel has no listings, so it is strong but not exhaustive.

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