Get JMS brokers

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

The annotation declares readOnlyHint=true, and the description's action verb 'List' aligns with that; there is no contradiction. The description adds useful context by warning about a possible 501 status, which is a behavioral trait not captured in the schema or annotations. This is a helpful addition beyond the structured data.

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 a single, short sentence with a parenthetical. It is concise and covers the main purpose efficiently. It is front-loaded with the core action and resource. Nothing is redundant, though it could have used the sentence to add a hint about parameter usage instead of the parenthetical.

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 description is minimal but the tool is a simple list operation with no required parameters, so the bar for completeness is lower. The annotations cover read-only behavior, and the parenthetical covers an edge case. However, given the low schema coverage and zero parameter documentation, a fuller description could have clarified what the parameters are for (e.g., OData-style queries), which would materially help an agent construct valid calls.

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%, meaning the schema provides no descriptions for the parameters, and the description does not explain what 'top', 'skip', 'filter', 'select', or 'orderby' mean or how they should be used. The description names none of the parameters. Since there are 5 parameters with no documentation anywhere, the description fails to compensate; a baseline of 3 is not justified.

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 the action ('List') and the resource ('JMS broker instances'), and it mentions 'status' as part of the output. It is clear enough to distinguish from the many sibling tools, though it does not explicitly name a sibling to contrast with. The phrase 'and their status' adds a bit of specificity.

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?

No explicit guidance on when to use this tool versus alternatives, but the context signal of the tool name and the sibling list make it clear it is one of many 'get_' tools. The parenthetical 'may return 501 depending on tenant' provides some situational context about availability, but there is no explicit when/when-not guidance.

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