Jira POST Request

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 does so effectively. It explains the default TOON output format for token efficiency, provides cost optimization guidance about using the jq parameter, warns about expensive unfiltered responses, and notes complexity for attachments. It also references the API documentation for further details, though it doesn't explicitly mention authentication requirements or rate limits.

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 and appropriately sized. It starts with the core purpose, then provides critical cost optimization guidance, output format details, and concrete examples of common operations. Every section serves a clear purpose - the examples help users understand parameter usage, the warnings address practical concerns, and the API reference provides further resources. No sentence feels wasted or redundant.

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 complex 5-parameter tool with no annotations and no output schema, the description provides substantial context. It covers the tool's purpose, usage guidelines, behavioral aspects like output format and cost optimization, and parameter usage through examples. The main gap is the lack of explicit information about authentication requirements, error handling, or rate limits, which would be helpful given the tool's complexity and mutation capabilities.

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?

With 100% schema description coverage, the baseline is 3, but the description adds significant value beyond the schema. It provides concrete examples for all parameters in the 'Common operations' section, showing how path, body, and jq work together for specific use cases. The cost optimization guidance around jq usage adds practical context that the schema alone doesn't provide, though it doesn't explain all 5 parameters individually.

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's purpose as 'Create Jira resources' with a specific verb ('Create') and resource type ('Jira resources'). It distinguishes from sibling tools like jira_get (read) and jira_delete (delete) by focusing on POST operations for creation. The opening sentence is direct and unambiguous about the tool's function.

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 explicit guidance on when to use this tool versus alternatives. It specifies this is for 'Create Jira resources' operations, distinguishing it from jira_get (read), jira_delete (delete), jira_patch/jira_put (update). The 'Common operations' section gives concrete examples of appropriate use cases like creating issues, adding comments, worklogs, and transitions, making it clear when this tool is the right choice.

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