jira_list_automation_rules

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar for additional disclosure is lower. The description adds a genuine behavioral fact — the operation routes only through the governed project/account connector authority — and notes that Spring verifies the effect field. But it omits other behavioral details like pagination, failure modes, or what happens when routing authority is missing, so the added value is thin. No contradiction with annotations exists.

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 compact and front-loaded: operation identity first, then the key routing constraint, then a terse parameter list. Each line earns its place without padding, and the parameter entries are consistently one line each. The only blemish is the approval_ref note ('when resuming a write') being mildly confusing inside a tool whose effect must be 'read'.

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 output schema and annotations reduce the burden by covering return values and the safety profile. But the description never clarifies which of project_id, project_ref, and connector_account_ref an agent must actually supply for a governed call, or how they interrelate — a meaningful gap given the central claim that the tool 'routes only through' that authority. The presence of approval_ref in a read operation also goes unexplained.

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 0%, so the description carries the full burden and it does gloss all seven parameters. The effect explanation ('Required and must be read; Spring verifies it') and idempotency_key ('Stable business-action identity') add real meaning beyond the schema's bare types and defaults. However, arguments ('JSON string of arguments for the connector operation') is near-circular and project_ref ('Exact project correlation reference') is opaque, so compensation is uneven.

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 verb+resource is recoverable from the name and first line ('list_automation_rules' on Jira), so an agent can tell this is a read-style list operation. However, the description mostly restates the platform tool name ('Jira connector operation `list_automation_rules`') and then pivots to a routing constraint ('Routes only through the exact project/account governed connector authority') without explaining what an automation rule is or what listing returns. It does not meaningfully differentiate from siblings beyond the verb embedded in the name.

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?

There is no guidance on when to use this tool versus alternatives, and no mention of obvious siblings such as jira_create_automation_rule or jira_delete_automation_rule. The routing sentence is a constraint about how the call is dispatched, not a selection criterion telling an agent when to choose this tool. An agent is left to infer usage purely from the name.

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