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

Annotations already declare readOnlyHint=true and destructiveHint=false, so this is marked as a safe read. The description adds value by specifying the response scope—'every occurrence the AI flagged with timestamps, the sessions behind it, steps to replicate, comments, and any linked external ticket'—which goes beyond the generic title. It doesn't contradict annotations, but doesn't describe error behavior or data volume, so it's not a full behavioral picture.

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 a single, well-structured sentence that front-loads the action and resource ('Get full detail for one AI-detected issue') before listing the included contents. It contains zero filler and every clause contributes meaningful information.

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 three parameters fully described in the schema, a read-only annotation, an output schema present, and a precise description of the returned data, an agent has all the information needed to select and call this tool correctly. The only minor omission, error handling when an issue isn't found, is low-stakes for a non-destructive read operation with an output schema.

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 100%, and each parameter has a meaningful description: issueId is 'Issue ID from list_issues', and domain/weekiteId explain workspace-token requirements. The tool description itself doesn't add any parameter-level semantics, so the baseline of 3 applies because the schema already does the heavy lifting.

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 uses a specific verb ('Get') and explicit resource ('full detail for one AI-detected issue'), then enumerates exactly what that detail includes: occurrences with timestamps, sessions, steps to replicate, comments, and linked external tickets. This clearly distinguishes it from siblings like list_issues (which lists issues) and update_issue_status (which mutates status).

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 phrase 'full detail for one AI-detected issue' clearly implies this tool is for retrieving comprehensive data about a single issue, as opposed to listing issues or updating status. However, the description itself does not explicitly name alternatives or state when not to use it; the schemas parameter description 'Issue ID from list_issues' hints at the intended workflow but is part of the schema, not the description.

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