atlassian-browser-mcp

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

Annotations indicate readOnlyHint=true, and the description aligns by describing a calculation operation without implying mutation. It adds valuable context beyond annotations by detailing configurable working hours via environment variables and specifying the return format as a JSON string, which helps the agent understand behavioral aspects like output structure and configuration dependencies.

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 clear sections (purpose, configuration, args, returns) and uses bullet points for environment variables, making it easy to scan. However, it includes some redundancy (e.g., repeating parameter names in the Args section that are already in the schema), which slightly reduces efficiency, but overall it is appropriately sized and front-loaded with key information.

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 the tool's complexity (calculating SLA metrics with configurable working hours), the description is complete. It covers purpose, configuration details, parameters, and return format. With annotations indicating read-only behavior and an output schema present (implied by 'Returns: JSON string'), no additional explanation of return values or safety is needed, making it fully adequate for the agent's use.

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 parameters. The description lists parameters in the Args section but does not add significant meaning beyond what the schema provides, such as explaining interactions between parameters or providing usage examples. This meets the baseline for high schema coverage.

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 ('Calculate SLA metrics') and resource ('for a Jira issue'), with explicit examples of metrics like cycle time, lead time, and time spent in each status. It effectively distinguishes itself from sibling tools like 'jira_get_issue' or 'jira_get_issue_dates' by focusing on SLA calculations rather than general issue data or date retrieval.

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 clear context for when to use this tool—when SLA metrics are needed—and mentions environment variables for configuration, which implies setup prerequisites. However, it does not explicitly state when not to use it or name alternatives among sibling tools, such as using 'jira_get_issue' for basic issue details instead.

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