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

There are no annotations, so the description carries the transparency burden. 'Key discarded' communicates a useful side-effect guarantee, and 'Check' implies a read-only validation. However, it does not disclose what the tool returns, whether invalid keys produce errors, or any other runtime behavior, leaving the transparency incomplete.

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 brief and front-loaded, with no filler words. Both sentences are short and earn some place, but the terseness comes at the cost of essential information about which input to use. Brevity is not effective when it leaves the agent unable to invoke the tool correctly.

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 a large, heterogeneous input schema, no annotations, and no output schema, so the description needs to do substantial work. It fails to state which property is the Jira key, what the validation result looks like, or how this differs from sibling shape validators. A one-line description cannot adequately cover this context.

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 description never identifies which input schema parameter contains the Jira issue key. The schema lists seven unrelated properties—ref, url, city, feed, host, json, path—and none is named 'key' or described in terms of Jira. 'Key discarded' does not map to any parameter, so an agent cannot determine what to pass. The core semantic connection between the tool's purpose and its inputs is entirely missing.

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 and resource: 'Check a Jira issue key shape.' This clearly distinguishes the tool from sibling shape tools like github-repo-shape or domain-shape by naming Jira specifically. It does not explicitly name a sibling tool, and 'key shape' largely restates the tool name, so it stops short of a perfect score.

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 gives no guidance on when to use this tool versus siblings such as github-repo-shape, figma-url-shape, or validate-json. It does not mention acceptable input formats, when the check is appropriate, or any exclusions. The only additional sentence, 'Key discarded,' is about retention, not usage context.

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