atlassian-browser-mcp

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context beyond annotations by mentioning included data (Epic links, relationship info) and error conditions (raises ValueError if Jira client unavailable), but doesn't cover rate limits, pagination, or authentication needs. No contradiction with annotations.

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 purpose statement, parameter details, return value, and error handling. However, the 'Args' section is verbose and largely redundant with the schema, adding unnecessary length. Front-loading is good, but some sentences don't earn their place given schema coverage.

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 100% schema coverage, annotations with readOnlyHint, and an output schema (implied by 'Returns: JSON string'), the description is complete enough. It covers purpose, parameters (via schema), behavior context, and errors, making it adequate for a read operation without needing to explain return values in detail.

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 100%, so the schema already fully documents all 6 parameters. The description's 'Args' section repeats schema information without adding significant meaning beyond it (e.g., doesn't explain field selection strategies or expand usage nuances). Baseline 3 is appropriate when schema does the heavy lifting.

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 specific action ('Get details') and resource ('specific Jira issue'), with explicit mention of included information ('Epic links and relationship information'). It distinguishes from siblings like 'jira_search' (which finds multiple issues) and 'jira_get_issue_watchers' (which focuses on watchers only).

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 usage context by specifying it retrieves details for a 'specific Jira issue', suggesting it's for known issue keys. However, it doesn't explicitly state when to use alternatives like 'jira_search' for finding issues or 'jira_get_project_issues' for bulk retrieval, nor does it mention prerequisites like authentication (covered by 'atlassian_login').

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