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

Annotations already establish read-only, idempotent, closed-world behavior, so the description needn't repeat that. It does add useful non-annotation context: results are restricted to accessible projects and the output is ids intended for downstream tools. It stops short of describing ordering, pagination behavior, or empty-result handling.

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?

Two compact sentences, front-loaded with the core purpose and followed by the return-value note. Slight imprecision in the example phrasing keeps it from being maximally tight.

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?

With no output schema, the description correctly tells the agent it receives ids for other tools, which is the most important missing piece. It still leaves gaps around result ordering, default OPEN filtering, and how many results to expect when limit is omitted.

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%, with descriptions and defaults for query, status, project_id, assigned_to_me, and limit, so the schema carries the parameter burden. The description mentions no parameters at all, so it adds nothing beyond the baseline.

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?

States a clear verb+resource ('Finds tickets') and scopes it to projects the user can access, with two concrete example use cases. It doesn't name the close sibling my_tickets, which handles the 'own open tickets' case, so the boundary is only loosely drawn.

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?

Usage is implied through examples ('the ticket to book time on, or the user's own open tickets'), which suggests search-before-mutate flows. However, it never says when to prefer this over my_tickets or get_ticket, nor what to do when no results are returned.

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