checkvist_get_checklist_stats

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

With annotations readOnlyHint and idempotentHint already declaring safety, the description adds value by detailing the nature of the statistics (number of tasks, top-level tasks, average depth) and the intended purpose. It does not contradict annotations and provides useful context about what the agent can expect from the response, without needing to discuss destruction or side effects.

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 and every part earns its place: the first sentence states the core function and examples of output, the second gives a clear usage directive. It is front-loaded with the verb and resource, and there is no wasted verbiage.

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 is simple (one parameter, no output schema), and the description adequately conveys what statistics are returned and when to use the tool. It provides enough information for an agent to invoke it correctly and interpret the response, though it does not enumerate every possible statistic or the exact response format. For the tool's complexity, this is largely complete.

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 100% since the sole parameter checklist_id has a clear description ('The ID of the checklist'). The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate; the schema fully documents the parameter and the description adds no extra nuance.

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 uses a specific verb ('Get statistics') and explicitly names the resource (a checklist) and the specific statistics returned (number of tasks, top-level tasks, average depth). This clearly distinguishes it from sibling tools like get_checklist or get_tasks, and the phrase 'Use this first' reinforces its distinct role.

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 guidance on when to use the tool ('Use this first to understand checklist size'), which is a clear usage context. It does not name alternatives or explicit when-not conditions, but the context strongly implies it is the initial reconnaissance step before other checklist operations.

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