BugSnag: Get Span Group

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

Annotations already declare readOnly and idempotent, and the description adds meaningful behavioral detail: it specifies that statistics include p50/p75/p90/p95/p99, that the response provides category and performance target info, and that span group IDs are automatically URL-encoded. This goes beyond the annotation safety profile without contradicting it.

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 and front-loaded: purpose first, then parameters, use cases, examples, and hints. It is somewhat long and repeats some schema parameter descriptions, but each section serves a practical purpose and the examples are directly actionable. It earns its length for a tool with no output schema.

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 absence of an output schema, the description does an excellent job of explaining what the agent will receive: statistics, category, performance target info, and filtered results. It also covers the workflow (discover span groups first), filter discovery, parameter defaults, and URL-encoding behavior. Nothing critical is missing for successful invocation.

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 baseline is 3. The description adds genuine value with the URL-encoding hint for spanGroupId, a concrete default filter value, an example of device.browser_name filtering, and a pointer to List Trace Fields for discovering filter fields. These details help agents use the parameters correctly beyond the schema text.

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 opens with a specific verb+resource: 'Get detailed performance metrics for a specific span group.' The word 'specific' distinguishes it from bugsnag_list_span_groups, and the performance-metrics focus separates it from other get tools like bugsnag_get_trace or bugsnag_get_error. This is clear and unambiguous.

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 'Use Cases' section clearly states when to use the tool (view percentiles, check performance targets, monitor span count). Hints provide routing guidance: use List Span Groups first to discover IDs and List Trace Fields to discover filters. It does not explicitly enumerate when-not-to-use alternatives, but the context is clear enough.

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