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

Annotations are neutral (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description must carry the burden of behavioral disclosure. The description mentions that setting count_only=true skips 'Case row selection, enrichment, and transformation', hinting that the default behavior may have side effects (modifying state or performing expensive operations). However, it does not clarify what these side effects are, whether the tool is rate-limited, or if it requires specific permissions. The description adds some transparency beyond annotations but leaves significant gaps, especially for a tool that might not be purely read-only.

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 three sentences, each serving a distinct purpose: first states the function, second provides usage guidance with an alternative, third explains a key parameter. It is front-loaded with the purpose, and every sentence adds value without redundancy or fluff. The length is appropriate for the tool's complexity.

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 has 8 parameters, a nested object, no output schema, and a moderate number of sibling tools, the description is incomplete. It covers the purpose, usage alternatives, and the count_only parameter, but it fails to describe the response shape in detail (beyond the count_only case), pagination behavior (limit/offset), the search parameter, sort options, or how to use the filters object. With no output schema, the description should provide more context about the expected outcome. The absence of this information means an agent may struggle to invoke the tool 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?

Schema coverage is only 25% (only queue_id and count_only have descriptions), so the description must compensate. The description explains the count_only parameter well: 'Set count_only=true to skip Case row selection, enrichment, and transformation. The normal response shape is returned with cases: [] and the matching total.' It also gives context for the filters parameter by mentioning 'rich filters (multi-status, date ranges, label-based filters)'. However, other parameters (limit, offset, search, sort_by, sort_order, and the inner structure of filters) are not described beyond what the schema provides. The description adds value for one parameter but does not fully compensate for the low 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 clearly states the tool's purpose: 'Search cases in a queue with rich filters'. It specifies the verb (search), resource (cases in a queue), and distinguishes from the sibling tool listCases by mentioning the simple query-string filters on GET /v2/queues/:queue_id/cases, which is a direct reference to the simpler alternative. The mention of explicit filter types (multi-status, date ranges, label-based) further clarifies the scope.

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 explicitly tells when to use this tool: 'Use this when the simple query-string filters on GET /v2/queues/:queue_id/cases aren't enough.' This provides clear guidance on the alternative and the context in which this tool is appropriate. It also explains the count_only option, adding a usage scenario. However, it does not explicitly state when not to use it (e.g., for simple listing) or provide prerequisites, but the guidance is sufficient for an agent to decide.

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