Get ticket history

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains that events are captured automatically by specific tools, that the timeline merges two data sources, and that it tolerates tickets with no recorded events (pre-FBMCPF-142). This is rich behavioral disclosure.

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, front-loading the main purpose. It avoids unnecessary words while including key details like the types of events and the edge case for older tickets. Minor improvement could be to separate the two data sources more clearly, but overall it is efficient.

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 2 parameters, no output schema, and moderate complexity, the description covers the main purpose and an edge case (tickets with no events). However, it does not describe the output structure (e.g., whether results are ordered, what fields are returned) which would help an agent understand what to expect. It is adequate but not fully 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?

The input schema has 0% description coverage, so the description must compensate. However, it only mentions 'one ticket' and 'project' implicitly; it does not explain the format, constraints, or relationship between the two required parameters. For a 2-parameter tool with no schema descriptions, the description adds minimal parameter guidance.

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 it returns a 'Full audit timeline for one ticket' and specifies the types of events (status moves, priority moves, etc.) merged with work-log entries. It distinguishes this tool from siblings by mentioning it combines field-change events and work logs, which is unique among related tools like get_ticket_diff or get_timeline_data.

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 implies this tool is for getting the combined history of a single ticket, but it does not explicitly state when to use it over alternatives (e.g., get_ticket_diff for diffs, get_timeline_data for timeline). No exclusions or conditions are given, so the guidance is adequate but not explicit.

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