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

The description discloses that the key is 'discarded', which hints at non-retention, but it does not explain what the tool returns, whether it accepts/rejects malformed keys, whether it makes external calls, or any side effects. With no annotations present, the description carrys the full behavioral burden and falls short.

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 extremely short and front-loaded, with the purpose in the first sentence and a behavioral note in the second. No words are wasted, though the second sentence adds little beyond what the schema descriptions already imply.

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 tool with no annotations, no output schema, and seven parameters, this two-sentence description is far from complete. It omits the expected result format, parameter mapping, and any error or validation semantics, leaving a critical invocation gap.

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 says 'Check a Jira issue key shape', yet the input schema contains no 'key' parameter. The seven parameters (ref, url, city, feed, host, json, path) are individually described in the schema, but none is tied to a Jira issue key, and the description does not bridge that gap. This leaves the agent unable to determine which parameter to pass.

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 clear verb and resource: 'Check a Jira issue key shape'. This makes the basic intent obvious and helps distinguish it from sibling shape-checkers like domain-shape or github-repo-shape. However, it does not specify what constitutes a valid shape or which input carries the key, so a bit of ambiguity remains.

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 implies use when a Jira issue key shape check is needed, but provides no guidance on when not to use it or how it compares to related tools such as normalize-url or validate-json. There are no exclusions, alternatives, or contextual conditions.

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