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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so excellently. It states the return payload ('Returns the image itself'), the supported formats and size limit (png, jpeg, gif, webp up to 5 MB), and the failure behavior for unsupported types ('videos and other file types are rejected with an explanatory error'). This is thorough and sets accurate expectations for the agent.

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 remarkably concise—three sentences in total—yet packs all essential information: purpose, return type, when to use, and constraints. It is front-loaded with the core action, then the use case, then limitations. Every sentence earns its place with zero redundancy or filler.

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 one-parameter download tool with no output schema, the description is complete. It tells the agent what the tool returns (the image), when to invoke it (based on get_issue attachments), and what constraints apply (formats, size, error behavior). There is no missing information an agent would need to call this correctly.

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 the schema itself already provides comprehensive parameter semantics (the attachment_id description explains it is a numeric ID from get_issue, NOT the issue key or filename, with an example). The tool description adds no additional parameter context beyond the schema, so the baseline of 3 is appropriate.

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 opens with a precise verb and object: 'Download an image attached to a Jira issue, for visual analysis.' This clearly distinguishes it from all sibling tools (whoami, get_issue, get_comments, get_issue_context, search_issues), none of which download binary content. The purpose is unambiguous and immediately actionable.

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 states when to use the tool: 'Use it when a ticket's Attachments section (from get_issue) lists a screenshot or other image relevant to the task,' and gives a concrete example (UI bug report). It also implicitly defines the boundary by noting only images (png, jpeg, gif, webp) up to 5 MB are supported, so an agent knows not to use it for videos or other file types. This is clear, concrete guidance with no ambiguity.

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

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

With no annotations, the description carries the behavioral burden. It discloses the output format (Markdown), the fields included (author, timestamp, edited, visibility restriction), and the scoping (only comments, not the issue body). Lacks mention of pagination or errors, but that's minor for a read operation.

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 sentences with zero waste. The first sentence front-loads the action and format, the second adds detail and usage guidance. Every word earns its place.

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 that input parameters are fully documented and an output schema exists, the description supplies the missing context: purpose, format, and when to use it. Nothing critical an agent needs to call it correctly 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 description coverage is 100%, so all parameters are already documented. The description adds no extra semantic meaning beyond the schema; it even reinforces the 'comment thread' concept but doesn't clarify parameter usage further. Baseline 3 is appropriate.

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 states a specific verb ('Get'), a precise resource ('comment thread of a Jira issue'), and the output format ('as Markdown'). It explicitly differentiates from the sibling get_issue, making the tool's scope immediately clear.

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?

Provides explicit when-to-use guidance: 'Use this instead of get_issue when the ticket body is already known and only the discussion is needed.' This names the alternative and the condition, leaving no ambiguity about tool selection.

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

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

No annotations are provided, so the description carries the full burden. It clearly states the output format (Markdown), enumerates the fields included, notes that only non-empty custom fields are returned, and references get_attachment for image handling. This is transparent about what the tool does and its default behavior (comments included). It does not mention error cases or permissions, but since it is a 'get' operation, it is reasonable to assume read-only. The description adds meaningful behavioral context beyond a bare statement.

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 paragraph with the core purpose front-loaded. Every sentence adds value, detailing the fields returned, the attachment list, and the comment behavior. It is slightly long but not wasteful, and the structure flows logically from general to specific. No redundancy or filler.

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's complexity, the description covers the essential return details, output format, and the relationship to get_attachment. Since an output schema exists, return values are not the description's responsibility. It addresses the main use case (full issue details) and the optional comment behavior. It stops short of describing error handling or authentication, but for a read-only getter with a rich schema, it is nearly 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?

Schema description coverage is 100%, so both parameters are already fully documented in the schema. The tool description adds minimal meaning beyond the schema—it reiterates that comments are on by default, which matches the schema default. It does not introduce new parameter semantics or clarify anything not already in the schema. Baseline 3 is appropriate here.

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 starts with a specific verb and resource: 'Get full detail for one Jira issue as Markdown.' It enumerates the exact fields returned, making its scope immediately clear. It distinguishes itself from siblings like get_comments (which returns only comments) and get_issue_context (context-specific) by stating what it covers, so an agent can tell it apart without opening schemas.

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 usage context by listing what it returns and mentioning that images must be fetched via get_attachment, but it does not explicitly state when to use this tool instead of get_comments or search_issues. The include_comments parameter hints that for just the ticket body you might set it False, but there is no explicit 'use X when Y' guidance. It provides enough to infer usage but lacks explicit exclusions.

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

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

With no annotations provided, the description carries the full burden of behavior disclosure. It reveals that results are resolved to key+type+status+summary, link direction is human-readable ('blocks' vs 'is blocked by'), and epics include their contained issues. This gives a solid understanding of what the tool does without mentioning side effects (likely a read-only operation) or authorization requirements, which are minor gaps.

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 two concise paragraphs with no filler. It front-loads the core purpose and then details the output structure and value proposition ('so the next issue to read can be chosen'). Every sentence contributes meaningful information, making it appropriately sized.

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 presence of an output schema (which presumably details the return type), the description gives an adequate high-level overview of what the tool returns. It covers the main categories (parent, subtasks, links, epic contents) and the format of resolved summaries. It doesn't mention potential errors or pagination, but for a graph-mapping tool this is not critical. The description is sufficient for an agent to decide to call the tool.

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 only parameter 'issue_key' is already fully described in the schema (e.g., 'Jira issue key like "PROJ-123"'), and schema description coverage is 100%. The tool description adds no additional semantics beyond what the schema provides, so it meets the baseline without enhancing understanding.

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 states a specific verb ('Map') and resource ('the reference graph around a Jira issue') and enumerates exactly what is returned (parent, subtasks, linked issues, and epic contents). It clearly distinguishes itself from siblings like get_issue (single issue), get_comments, search_issues, and get_attachment by focusing on relationships rather than raw issue data. The purpose is immediately unambiguous.

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 when to use it: when you need to decide which issue to read next based on the relationship graph ('so the next issue to read can be chosen without further calls'). It doesn't explicitly mention when not to use it or list alternatives for cases like retrieving a single issue, but the context is clear enough for an agent to infer appropriate usage.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the output format (Markdown list with specific fields per line), the cap on results via the limit parameter, and that the output notes when more matches exist. This goes beyond a bare 'returns search results' and gives the agent a concrete expectation of what will happen.

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 four sentences with no fluff. The purpose is front-loaded, an example is provided, and the cap/note behavior is clearly stated. Every sentence adds operational value, making it compact and easy to parse.

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 simple two-parameter tool with an output schema, the description covers all essential aspects: what it does, how to invoke it (with example), what the result lines contain, and the constraint on limit. The output schema handles field definitions, so the description need not repeat them. Nothing critical for correct invocation is missing.

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% for both parameters, so the baseline is 3. The description adds value beyond the schema by specifying that results are capped at limit (1-100), which is not in the schema (no min/max defined), and by providing an example JQL query that clarifies usage. It also notes that any length/complexity works, which the schema already hints at but is reinforced here.

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 starts with a clear verb+resource: 'Search Jira with a JQL query' and specifies the output format as a compact Markdown list. It distinguishes itself from sibling tools like get_issue or get_comments by focusing on search across issues rather than retrieving a single known entity.

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 provides context for when to use the tool (when you need to find issues matching a JQL query) and includes an example JQL. However, it does not explicitly mention when NOT to use it or name alternatives (e.g., 'use get_issue to fetch a single issue by key'). The routing to siblings is implied but not stated, so it falls short of a 4.

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

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

With no annotations, the description carries the full burden. It explains the tool's read-only nature implicitly ("Report") and details the base URL selection logic (site URL vs cloud-ID fallback). However, it does not explicitly state that no modifications are made, which would be a slight improvement.

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 concise, with the primary purpose stated in the first sentence and return details and usage guidance following logically. Each sentence earns its place without redundancy, and the structure front-loads the core function.

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 parameterless tool with an output schema, the description fully covers its function, return content, and a specific usage scenario. No additional context is needed for an agent to invoke it correctly.

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 tool has no parameters, so schema coverage is trivially 100%. The description adds significant value by specifying exactly what information is returned (display name, email, account ID, base URL), going beyond the empty schema and enriching the agent's understanding.

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 tool reports the authenticated Atlassian account, listing specific return fields (display name, email, account ID, base URL). It distinguishes itself from siblings by focusing on authentication, not issues or comments.

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?

It explicitly instructs to call this tool first when other tools return authentication or permission errors, providing a clear when-to-use directive. This guidance helps agents isolate credential vs. resource problems, which is directly actionable.

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