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

Annotations already establish readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context on top: the hard cap of 3 bikes, that both spec and valuation data come back in one call, and the provenance ('same measured UK data'). It says nothing about behavior when a brand/model is unknown or unmatched, which is the main remaining blind spot.

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?

Three sentences plus an example, front-loaded with the verb and the cap. The clause tying the data to the single-bike spec sheets and valuations is slightly wordy but earns its place by anchoring data consistency. Nothing is redundant with the title.

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?

An output schema exists, so return values need not be spelled out, and the read-only annotations cover the safety dimension. For a single-parameter, read-only comparison tool the definition is nearly sufficient; only error/partial-match behavior is unaddressed.

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%, so the description carries the load: 'each by brand+model[+year]' documents the nesting of the bikes array and flags year as optional, and 'up to 3 bikes' supplies a cardinality constraint the schema does not encode (there is no maxItems). It does not address year formatting or duplicate handling, but the essential shape is conveyed.

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?

States a specific verb and resource ('Side-by-side comparison of up to 3 bikes') plus what is returned ('spec sheets and valuations together'), which implicitly separates it from the single-bike get_spec_sheet and get_valuation siblings. An agent can distinguish it from those siblings without opening any schema.

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 worked example ('compare a Trek Domane SL 6 against a Specialized Roubaix Comp') gives a clear context for when to reach for this tool, and the 'up to 3 bikes' cap signals batch usage. It stops short of an explicit exclusion such as 'for a single bike use get_spec_sheet / get_valuation instead', so routing for the n=1 case is left to inference.

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