review_ticket

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

Annotations already establish readOnlyHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: that every finding cites a count over the exemplar sample and that this numerical grounding is the difference between this advice and generic advice. This tells the agent something about output provenance that annotations cannot convey. No contradiction with annotations; 'measure' is consistent with readOnlyHint.

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 tight sentences with zero filler. The purpose sentence is front-loaded, and the second sentence earns its place by adding a critical presentation instruction (repeat the counts to the user). No redundant restatement of the tool name or schema fields.

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 single-ticket comparison tool with an output schema present, the description is largely sufficient: it explains the measurement target, the grounding mechanism (counts over exemplar sample), and how to relay results. The main omission is the role of the two optional parameters, project and tracker, which are used in nearly every call context and deserve a sentence. Output schema covers return values, so that burden is already lifted.

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%, so the description must compensate, and it only weakly does. The phrase 'one ticket' clarifies that 'ticket' is the object being measured, but 'project' and 'tracker' are entirely unexplained — the agent cannot tell whether they filter the exemplar sample, scope the house style, or constrain the comparison. With two of three parameters undocumented in both schema and description, this is a real gap.

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 first sentence states a specific verb ('Measure'), a clear resource ('one ticket'), and the comparative frame ('against the learned house style'). It distinguishes itself from siblings by scoping to a single ticket, which contrasts with review_open_tickets (bulk) and review_draft (drafts, likely pre-submission). The scope word 'one' plus 'house style' anchors exactly what this tool does.

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 context is implied through the comparative frame (measure a ticket against house style), but no explicit when-to-use or when-not-to-use guidance is given, and no sibling alternatives are named. It doesn't tell the agent when to prefer this over review_draft or house_style. The only concrete usage instruction is 'Repeat those numbers to the user,' which is a presentation directive rather than a selection rule.

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