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

Annotations declare idempotentHint:true, but the description adds substantial behavioral context beyond that: it states that the tool adds the order-settings step and leaves syncing OFF, that status can be 'updated' (added or already on) or 'prerequisite_not_met', and that it returns a specific object shape. It also clarifies that it is a capability enabler, not a toggle, which is a non-obvious nuance. The description complements and extends the annotation rather than contradicting them.

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?

The description is dense but every sentence earns its place: it defines the tool, distinguishes it from the mode toggle, explains the prerequisite, outlines the workflow, defines return values, and specifies both parameters. It is organized logically from definition to mechanics to follow-up actions, and it front-loads the core distinction. Length is justified by the tool's complexity; there is no filler or repetition.

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?

Given the tool's complexity, the absence of an output schema, and the 0% schema coverage, the description covers everything an agent needs: the exact purpose, the precondition, the post-step workflow referencing sibling tools (configure_marketplace_step, set_marketplace_order_mode, list_marketplaces, list_projects), the return object structure, and the domain restriction. Nothing essential 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?

The input schema has zero description coverage (0%), so the description must carry the full burden for both parameters. It does: it explains that marketplace_id comes from list_marketplaces, and that project_id is optional when the customer has a single project but required otherwise, and to call list_projects if needed. This fully compensates for the schema's silence.

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 states a precise verb+resource: 'Add ORDER SYNC to an existing marketplace' and immediately distinguishes the capability from the on/off switch, framing it as 'the capability, not the on/off switch.' It explicitly names the alternative tool (set_marketplace_order_mode) and specifies that this tool turns the capability ON for marketplaces created without it. This leaves no ambiguity about what the tool does or how it differs from its siblings.

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?

The description gives explicit when-to-use and when-not-to-use guidance: only offer it when get_marketplace reports canEnableOrderSync:true, and that otherwise it returns 'prerequisite_not_met' (HTTP 409). It also details the full following workflow: re-fetch get_marketplace, configure the new 'order-settings' step with configure_marketplace_step, then call set_marketplace_order_mode enabled:true. It even explains the marketplaces-only limitation. This is thorough and leaves no inference to the agent.

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