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

The description adds important behavioral details beyond annotations, such as the server's conversion to multipart, the requirement for base64 with binary files, and the non-idempotent behavior ('Uploading the same file twice creates two Jira attachments'). These details align with annotations but provide context the annotations do not.

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, all containing necessary information. It front-loads the main purpose, then adds technical and behavioral details without any fluff. Every sentence 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 the tool's complexity (5 parameters, encoding constraints), the description covers the key usage aspects: target, encoding rules, and idempotency. Since an output schema exists, return values are already documented. The description is sufficient for correct selection and invocation.

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%, so the baseline is 3. The description adds value by explaining the encoding semantics: 'Binary files must use encoding=base64' and that the server converts UTF-8/base64 content. This goes beyond the schema's enum descriptions, providing practical guidance for using the content and encoding parameters.

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 'Upload one attachment to a Jira issue or Jira Product Discovery idea,' which specifies the verb, the resource, and the scope. This distinguishes it from sibling tools like jira_post or jira_create_jpd_insight, making the purpose 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 the tool (when uploading an attachment) but does not explicitly mention alternatives or provide exclusions. It lacks a direct contrast with generic HTTP methods like jira_post, so the guidance is only implied rather than explicit.

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?

The description discloses that the server builds a fixed ADF description, uses existing OAuth, and intentionally does not create a structured snippet. This goes beyond annotations (which only indicate write operation, open world, not idempotent). However, there is some ambiguity about how the 'description' parameter is used given the fixed ADF construction.

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, front-loaded sentences. Every sentence adds information: the first states the core action, the second explains server-side behavior and auth. No waste.

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 an output schema present, return values need not be described. The description covers key behavioral aspects (ADF construction, OAuth, no snippet). Some side-effect details are omitted, but the description is sufficiently complete for a creation tool with annotations.

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 100% coverage with descriptions for all 5 parameters, so the baseline is 3. The description adds minimal new parameter semantics—it mentions summary/quote/linked source but does not clarify the role of each parameter beyond what the schema already provides.

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 creates a 'native Jira Product Discovery Insight' with a specific verb and resource. It distinguishes itself from sibling tools like jira_post by focusing on JPD insights specifically.

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 creating JPD insights and mentions the use of existing OAuth, but it does not explicitly compare to alternatives like jira_post or state when not to use it. Since siblings include a generic jira_post, more explicit guidance would help.

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?

Without annotations, the description carries the full burden. It discloses default output format (TOON), the option for JSON, the typical 204 No Content response, and includes endpoint examples. It does not mention the potential irreversible nature of deletions or authentication requirements, which would be useful for a destructive tool.

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 well-structured with clear sections for output format and common operations. Though moderately long, every section is informative and non-redundant. The numbered list for operations enhances scannability, and the summary sentence is front-loaded.

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?

The description covers output format, specific paths, query params, response status, and provides an API reference. Given that there is no output schema, this is sufficiently complete for a delete tool, which often returns 204 or minimal bodies.

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 schema descriptions are already thorough (100% coverage), and the description adds significant value by giving exact endpoint templates and query parameters for each operation, such as '/rest/api/3/issue/{issueIdOrKey}' and 'deleteSubtasks=true'. This goes well beyond the raw schema and helps the agent construct valid requests.

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 'Delete Jira resources' and lists specific operations (delete issue, comment, worklog, attachment, watcher), which distinguishes it from sibling tools like jira_get, jira_post, etc. The verb 'Delete' and resource examples make the purpose unmistakable.

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 concrete common operations with endpoint patterns, making it clear when to use this tool for various delete tasks. However, it does not explicitly contrast with alternatives or state when not to use it, though the name and sibling context make this largely implicit.

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. It discloses the token-efficient TOON output format, the cost implications of unfiltered responses, and the schema discovery pattern. It does not mention error handling or authentication, but it provides substantial behavioral context beyond what the schema and annotations could offer.

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 long but well-structured with sections, bullet points, and examples. Every section serves a purpose: cost optimization, schema discovery, common paths, and examples. It is front-loaded with the main purpose and cost warning. No extraneous filler, though it could be trimmed slightly without losing value.

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 no annotations and no output schema, the description compensates by covering common paths, JQL examples, output format, and cost-saving techniques. It also links to the full API reference. It does not describe error responses or return structures, but for a read tool with this level of guidance, it is remarkably 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 schema already provides descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds significant value by providing concrete examples for path, queryParams, and jq expressions, and by explaining the outputFormat enum. This goes beyond the schema to clarify usage and cost optimization.

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 "Read any Jira data," which clearly identifies the tool as a read-only GET operation. It distinguishes from sibling tools like jira_post, jira_put, jira_patch, and jira_delete, which are all mutations. The scope is broad but well-defined as covering all Jira 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 provides strong guidance on how to use the tool efficiently (use jq, maxResults, schema discovery pattern) and even warns against deprecated paths. However, it does not explicitly state when to use this tool versus alternatives (e.g., the write siblings), though this is implied by the verb 'Read' and the sibling names.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these annotations: it explains the server resolves internal IDs and ARIs, returns a normalized response, and never exposes raw GraphQL or provider envelopes. This goes beyond what the annotations alone communicate.

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 sentences: one clear purpose statement and one concise behavioral note. No filler or redundant content, and it is front-loaded with the primary 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?

The tool is simple (1 parameter), has an output schema, and has comprehensive annotations. The description covers purpose and behavior adequately, and it does not need to explain return values because the output schema exists. This is complete for the tool's complexity.

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 sole parameter ideaKey is fully described in the schema with a pattern and description. The tool description's phrase 'for an idea key' adds no new semantic information beyond the schema, so with 100% schema coverage the baseline score 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 starts with 'List native Jira Product Discovery Insights for an idea key', which uses a specific verb ('List'), a clear resource ('native Jira Product Discovery Insights'), and a precise scope ('for an idea key'). This clearly distinguishes it from generic siblings like jira_get and jira_create_jpd_insight.

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 clearly implies when to use the tool: when you need native Jira Product Discovery Insights for a given idea key. However, it does not explicitly state when not to use it or mention alternative tools, which would elevate it to a 5.

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 of behavioral disclosure. It discloses the default output format (TOON), the option to switch to JSON, the cost-optimization with jq, and the partial-update semantics. It does not mention authentication, error handling, or rate limits, but the provided behavior is substantial for a generic REST client.

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 well-structured with clear sections for introduction, cost optimization, output format, common operations, and a note on PATCH semantics. Despite its length, each sentence provides valuable information, and key details like partial update behavior and output format are front-loaded.

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?

The description is thorough for a tool with five parameters, nested objects, and no output schema. It covers common use cases, parameter examples, and output behavior. It lacks details on error responses and authorization, but the provided information is sufficient for typical invocation and is complemented by an API reference link.

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?

Although the schema already has 100% coverage, the description adds significant meaning beyond parameter names by providing concrete body examples for different update operations (issue, comment, worklog), path patterns, and jq usage for response filtering. This enriches the schema descriptions with practical usage context.

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 performs partial updates to Jira resources, using the specific verb 'PATCH' and identifying the resource scope. It distinguishes itself from siblings by emphasizing partial updates that leave other fields unchanged, contrasting with jira_put for full updates.

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 clear context for when to use the tool, such as updating issue fields, comments, and worklogs. It explicitly notes that PATCH only updates specified fields, implying it's for partial modifications. However, it does not explicitly name alternatives like jira_put or jira_post for full updates or creation, though the sibling names make this inferable.

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 for behavioral disclosure. It discloses output format (TOON vs JSON), cost implications of unfiltered responses, and the importance of jq for token efficiency. It also notes that unfiltered responses are 'expensive.' It stops short of mentioning auth requirements, rate limits, or side effects beyond 'create,' but the provided context is substantial.

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 lengthy but well-structured with clear sections: intro, cost optimization, output format, common operations, API reference. It front-loads the most important guidance about jq filtering and cost. Minor redundancy exists (TOON mentioned twice as default), but overall the length is justified by the tool's complexity and multiple use cases.

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 (5 params, multiple endpoint patterns, no output schema), the description covers the key aspects: input examples, output format, cost optimization, and a link to full API docs. It does not detail response structures or error handling, but it provides enough for an agent to correctly construct requests and parse responses via jq. This is strong for a generic POST wrapper.

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%, so the baseline is 3. The description adds meaningful value by showing exact body structures for four common operations, jq usage examples, and outputFormat guidance. This goes beyond the schema's parameter descriptions, providing real-world usage patterns and endpoint-specific payloads.

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 'Create Jira resources,' a specific verb+resource statement that clearly defines the tool's purpose. It differentiates from siblings like jira_get, jira_put, etc., by referencing the POST method and lists concrete use cases (create issue, add comment, add worklog, transition issue). It also explicitly directs attachment creation to a sibling tool, further clarifying scope.

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 'Common operations' with endpoint paths and request body examples, implicitly guiding when to use this tool for POST-style operations. It explicitly says to use jira_add_attachment for attachments, which is a clear alternative. However, it does not explicitly contrast with PUT/PATCH/DELETE for update/delete operations, only showing POST use cases.

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 discloses that PUT replaces the entire resource (a key destructive behavior), explains the default TOON output format, and highlights the jq parameter for cost optimization. It does not mention permissions or failure modes, but the disclosed behaviors are substantial and useful.

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 well-structured with bold headers, a clear one-sentence summary, and a numbered list of examples. It is slightly longer than minimal, but each section serves a purpose—clarifying output format, cost optimization, and typical endpoints—so it remains 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?

The tool has no output schema and moderate complexity (5 params, nested body). The description covers key operational contexts: full-update semantics, default output format, and common use cases. It could mention idempotency or authentication, but HTTP PUT semantics and the API reference provide sufficient completeness 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?

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by providing concrete example paths and bodies for common operations, and by reinforcing the purpose of jq in reducing token costs. This goes beyond simple schema repetition.

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 'Replace Jira resources (full update)' which precisely states the action and scope. The note 'For partial updates, prefer PATCH' explicitly distinguishes it from the sibling jira_patch tool, making the purpose 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?

Usage guidance is explicit: it states when to use PUT (full replacement) and when not to (partial updates, prefer PATCH). It also provides common operation examples (update issue, update project, set property) and a cost-optimization tip with jq, which further clarifies appropriate usage.

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