Side-by-side comparison of up to 3 bikes (each by brand+model[+year]). Returns spec sheets and valuations together so the user can pick. Reuses get_spec_sheet + get_valuation server-side. Example: 'compare a Trek Domane SL 6 against a Specialized Roubaix Comp'.
| Name | Required | Description | Default |
|---|---|---|---|
| bikes | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections. Dates show when Glama detected each change.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral context: it performs a server-side combination of two other tools, returns both spec sheets and valuations, and has a hard limit of 3 bikes. This goes beyond what annotations provide without contradicting them.
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 two sentences plus a relevant example. It is front-loaded with the core purpose, then provides the key constraints and an illustrative use case. Every sentence contributes meaning without redundancy.
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 covers the essential inputs (up to 3 bikes, brand+model+year), what it returns (spec sheets and valuations), and how it works (reusing other tools). With an output schema present, return values need not be explained. Minor gaps like behavior with fewer than 2 bikes or error handling are not critical for a read-only comparison tool.
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?
The input schema simply defines a 'bikes' array with brand, model, and optional year, but provides no descriptions. The description compensates by explaining each bike is identified by brand+model[+year] and gives an example, making the parameter structure clear. It could be even more explicit about the types, but the example helps.
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 verb 'compare' and the resource 'bikes', with a specific function: side-by-side comparison of up to 3 bikes returning spec sheets and valuations. It distinguishes itself from sibling tools like get_spec_sheet and get_valuation by combining both into one call.
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 when the user needs both specs and valuations together to pick a bike, and explicitly mentions it reuses get_spec_sheet + get_valuation server-side, hinting at alternatives for single lookups. It also gives a concrete example. However, it does not explicitly state when NOT to use it or name alternatives directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
