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

The readOnlyHint annotation already discloses the read-only nature, and the description's verb 'List' is consistent with that. The description adds value by including a concrete example of the return payload, which helps the agent understand the shape and fields of the result. It does not contradict annotations, and while it doesn't discuss rate limits or auth, those are not expected for a simple list operation with this level of annotation coverage.

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 two sentences: the first states the purpose and intended use, the second provides a compact example of the return structure. Every element earns its place, with no filler or redundancy. The purpose is front-loaded, and the example is succinctly formatted.

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 list tool with one optional parameter and no output schema, the description is complete. It clearly states what the tool does, why it is used, and includes an example of the response structure. The annotation covers the read-only safety aspect, and the schema covers parameter details. There are no missing pieces an agent would need to call it correctly.

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 provides a thorough description of the site parameter, covering accepted formats (numeric ID or domain), normalization behavior (scheme/www/path ignored), error handling for shared domains, and the omission rule. Since schema description coverage is 100%, the tool description adds nothing beyond the example output, which pertains to the response rather than the parameter. A baseline of 3 is appropriate because the schema fully documents the parameter.

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 clearly states the action: 'List the conversion funnels configured for a site'. It specifies the resource (funnels) and the scope (per site), and explicitly frames it as a discovery step to obtain a funnel_id for funnel_report. This distinguishes it from sibling tools like create_funnel or funnel_report without ambiguity.

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 includes a parenthetical '(discovery — get a funnel_id for funnel_report)' that explicitly states when to use this tool: as a precursor to funnel_report. The schema further elaborates usage conditions, such as omitting the site parameter for single-site keys and the behavior when multiple sites share a domain. Together, these provide clear guidance on when and how to invoke the tool.

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