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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds important context beyond those hints: the capability list is dynamic and merchant-configurable, and the default is fully open unless the merchant narrows it. It also explains that passing an exact capability name returns full details. This is useful behavioral context not derivable from annotations. It does not, however, mention any rate limits, pagination, or whether the list can be empty.

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 front-loaded with the core purpose and then details the categories and search behavior. It is a single, dense paragraph but well-structured. One could argue a small amount of repetition (e.g., 'see connected_sites' appears twice), but overall it is efficient and focused.

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 read-only discovery tool with no output schema, the description adequately explains what the tool returns (a list of capabilities with arguments) and how to interact with it (search). It mentions the dynamic nature and merchant control. It does not specify the return format in detail, but since there is no output schema, more detail could be helpful; still, the description covers the essentials for correct invocation.

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 description coverage is 100%, so both parameters (site and search) are fully documented in the schema. The description adds meaning for search by explaining that it can narrow the list or, with an exact capability name, read that capability in full. This is a useful semantic addition but not a replacement for schema documentation, which already covers the parameters. Baseline 3 is appropriate given full schema 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 states a specific purpose: it enumerates what a connected WhizzyCommerce shop lets an AI do right now, as a list of capabilities with their arguments. It explicitly distinguishes itself from whizzy_call by being a discovery/catalog tool rather than an invocation tool, and from connected_sites by referencing that tool for site context. No sibling does the same job.

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 clear usage context: default behavior is everything open, the merchant can narrow it, and a search term can narrow the list or read a single capability in full. However, it does not explicitly state when to use this tool instead of alternatives (e.g., when to use this vs. whizzy_call, or whether this is a prerequisite step). It implies usage but lacks an explicit 'use this when...' routing statement.

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