count_tickets

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

No annotations are provided, so the description carries the full burden. It does disclose useful behaviors such as case-sensitive stage values, partial-match search, include_merged defaulting to false, and auto-resolution of user display names. However, it does not state how multiple filters combine (AND vs OR), whether the count is capped, or explicitly confirm this is a read-only operation. These are notable gaps for a counting tool.

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 a one-sentence purpose and alternative tool recommendation, followed by a structured args list. Every line adds value: no fluff, no repetition, and all parameter descriptions are succinct. It is long only because it covers 10 parameters meaningfully.

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 output schema exists, so return values need not be explained. The description covers all 10 parameters and provides necessary context for valid values. The only missing element is an explicit statement about filter combination semantics (AND/OR), which is important for a counting tool. Overall, it is nearly 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 description coverage is 0%, yet the description fully compensates by explaining every parameter with examples and meaning. It provides valid values for stage/priority, clarifies that contact expects an ID not a name, gives date format, and describes search behavior. This goes far beyond the schema.

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 opens with 'Count tickets matching filters,' which clearly states the verb+resource. It also explicitly distinguishes from list_tickets: 'Use this instead of list_tickets when you only need a number.' This makes the tool's purpose unmistakable.

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?

Explicit guidance is given for when to use this tool over a sibling: 'Use this instead of list_tickets when you only need a number.' Additionally, parameter-level instructions recommend calling list_ticket_categories, list_contacts, and list_statuses where needed, and clarify that user display names are resolved automatically, removing the need for list_users.

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