Get the session replay link of a bug

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

Beyond the annotations that already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds valuable behavioral context: it explains the scoping by FEEDBUG_PROJECT_KEY, that missing recordings return a non-error message ('No session replay available'), and that the call is always safe to attempt. There is no contradiction with annotations.

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 exceptionally concise at four short paragraphs, each with a distinct purpose: the first paragraph states the action and scope, the second describes the output and cost, the third provides usage guidance, and the fourth covers behavior. Every sentence earns its place, and the structure is front-loaded with the core purpose.

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 only one parameter, no output schema, and annotations already cover safety, the description is fully complete: it covers the idiosyncratic return format (one-line message), special case (no recording), scoping to project key, and how to call feedbug_get_bug to avoid redundancy.

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% and the description does not repeat parameter details, but it complements the schema by explaining the id can be a UUID or tracker identifier like 'PRE-13', matched case-insensitively, and clarifies that ids from other projects are rejected — adding meaningful value 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 clearly states the verb 'Read' and the specific resource 'session replay URL of a bug', and distinguishes it from siblings by noting that feedbug_get_bug returns the same URL alongside other data, while feedbug_get_replay focuses on just the recording link.

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 explicitly says 'Use when' the written report is insufficient and you want to provide a link, and 'Do not use when' you already called feedbug_get_bug (which returns the same URL), offering clear guidance on when to choose this tool over alternatives.

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