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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower, yet the description adds real behavioral context beyond them: the side effect boundary ("Sends nothing to the channel") and the returned envelope fields. That tells the agent exactly how far the mutation reaches, which the annotations cannot express.

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 core definition and alternative routing before any parameter detail, which is the right order. It is dense to the point of being cramped, though — semicolon-chained clauses and the inline return-shape string make it harder to scan than it needs to be, without any single sentence being wasted.

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?

The tool has only two params, no output schema, and simple annotations; the description nevertheless covers scope, side effects, return shape, parameter provenance, and the error path for a missing project. Nothing an agent needs to call this correctly is absent.

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% (project_id is undocumented in the schema), and the description fully compensates: it says project_id is OPTIONAL, explains the inference for single-project customers, names the project_id_required failure mode, and points to list_projects as the recovery call. marketplace_id provenance is also restated from list_marketplaces.

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?

"Switch a marketplace to MANUAL product mode" states a specific verb and resource, then immediately defines the operational consequence ("nothing is published automatically; items reach the channel only through submit_marketplace_items"). That definition cleanly separates it from set_marketplace_auto_mode and pause_marketplace without the agent 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?

It gives two concrete use cases ("to test before activating", "to stop automatic publishing") and explicitly names the sibling for a different intent: "to stop all syncing use pause_marketplace". That is an explicit when-to-use plus when-to-use-something-else, which is the top of this scale.

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