cyclesite-mcp-server

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

Adds substantial behavior beyond the annotations: live data checked on every call, a rate limit of 3 per hour per serial number, and the anti-enumeration rationale behind it. This is exactly the quota information an agent needs before deciding how often to call.

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?

Front-loads the purpose, then layers behavior, then usage. The example query and the found-bike link are both short and useful, and there is no filler.

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 described, and the description covers purpose, limits, and the adjacent workflow. It does leave open why the annotation marks this non-read-only when the tool reads live data, which an agent might wonder about for side effects or quota accounting.

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?

With a single parameter at 100% schema coverage, the schema already documents the serial parameter and its 4-50 char constraint. The description contributes meaning only indirectly, by framing the serial as a UK bike frame number, so it cannot exceed the baseline.

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?

Names a specific verb and resource: check whether a UK bike's frame (serial) number matches a Cyclesite theft report. This clearly distinguishes it from the sibling report_stolen, which files a report instead of looking one up.

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?

Gives a concrete example query and a clear alternate use case — someone who found a bike can check and message the owner via the given URL. It does not explicitly rule out adjacent cases (e.g. checking a bike you are about to buy vs. one you already own) or name report_stolen as the tool for the inverse action.

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

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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description is consistent with that by explicitly saying nothing is published. It adds genuinely useful context beyond the annotations: the OAuth requirement for the downstream publish step and the fact that the output includes a suggested price and photo plan. It does not explain why idempotentHint=false (i.e., that repeated drafts may differ), which is the one behavioral trait an agent would most benefit from knowing.

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?

Four sentences, front-loaded with the core purpose and then the non-publishing constraint, with the worked example earning its place by showing the expected input shape. Slightly dense parentheticals, but no filler.

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 described, and the auth/publish boundary is covered. However, for a 10-parameter tool with 20% schema coverage, the description leaves too much of the input surface unexplained for an agent to fill a good draft confidently.

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 coverage is only 20% — just knownIssues and itemCondition carry descriptions — and the prose does not compensate for the other eight. The example mentions year, condition and city, which maps loosely onto three fields, but required fields (brand, model), groupset, frameSize and willShip get no explanation of format or effect on the draft.

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 uses a specific verb and resource ('turn a seller's raw facts into a polished Cyclesite listing draft') and enumerates the produced artifacts: title, description, suggested price, photo plan. It also implicitly separates itself from the publishing siblings by stating 'Does not publish anything', so an agent can route between drafting and publishing without opening either 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?

It establishes the usage context ('sell-side helper', 'useful for previewing what a listing would look like') and states the exclusion that publishing requires a signed-in OAuth account, which is a real gating condition. What it lacks is an explicit pointer to named siblings such as publish_listing or suggest_listing_price, so the agent must infer the handoff.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds the return shape and the key trait that "text is a plain-prose summary ... suitable for direct quoting", which is genuine behavioral context. It does not cover error behavior, rate limits, or whether the prose loses structured spec precision.

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?

Two sentences with the resource statement front-loaded and the return contract second; nothing is padded. The leading compatibility clause is slightly jargon-heavy but does earn its place by signalling the intended calling context.

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?

For a one-parameter read tool with full annotation coverage and an output schema, the description is essentially sufficient, and it even restates the return fields. The remaining gap is sibling differentiation against get_listing_detail, which an agent would need in order to choose correctly.

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% and there is a single required id, so the schema does the documentation work. The description only adds the qualifier "Cyclesite listing id", which conveys domain scope but no format or source guidance. Baseline 3 applies.

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: "Fetch the full document for one Cyclesite listing id." An agent can tell this is a per-listing full-document retrieval. However, it never distinguishes itself from near-neighbours like get_listing_detail or get_spec_sheet, so the boundary is left to inference.

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?

"OpenAI deep-research / company-knowledge compatibility" implies the context in which this is called (connector/deep-research flows) rather than a normal listing lookup, which is useful. But there is no explicit when-to-use versus get_listing_detail, no exclusions, and no statement of what happens for an invalid or missing id.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real behavior beyond them: the 5-result cap, the requirement that results be active, and the ranking heuristic used to pick and order matches.

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?

Everything is packed into one dense sentence plus a short example, front-loaded with the output shape ('up to 5 similar active listings'). The parenthetical ranking criteria are slightly compressed but each clause carries 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?

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. What remains — what counts as similar, the result cap, and the intended user intent — is all supplied; only explicit sibling routing is missing.

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 coverage is 100% and the single parameter already documents itself as the source listing URL slug. The description confirms the slug identifies the source bike but adds no format or edge-case detail beyond the schema, so baseline 3 applies.

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 names a specific verb and resource ('Given a Cycle site listing slug, return up to 5 similar active listings') and pins down the notion of similarity with concrete criteria (same category, ±25% price, brand/frame size weighting). This clearly separates it from retrieval siblings like get_listing_detail or search_bikes.

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 example utterance ('show me bikes like that one') makes the triggering intent clear: the user has one listing in mind and wants alternatives. It does not explicitly exclude alternatives such as search_bikes or compare_bikes, so it stops short of full when-not guidance.

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

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

Beyond the read-only, idempotent, closed-world annotations, it discloses the curated corpus, its authorship, and its educational rather than live-inventory scope. The unqualified claim that it returns 'up to 3' guides is slightly misleading because the schema permits limit values through 5, although it matches the default.

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 compact and front-loads the searchable resource before covering scope and examples. Its result-metadata sentence is somewhat redundant with the output schema, but the overall wording remains efficient and easy to scan.

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?

Together with the complete input schema, output schema, and safety annotations, this provides nearly everything needed to select and invoke a simple guide search. Explicit routing to search_bikes or get_size_guide and consistent wording about the configurable result limit would close the remaining gaps.

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 coverage is 100%, so both query and limit are already documented and the baseline is 3. The full-question examples add some guidance on natural-language queries, but the description adds no new limit semantics and its three-result wording can obscure the ability to request more.

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 opening sentence gives a specific verb and resource: searching Cyclesite's expert buying guides within a bounded 24+ article corpus. The statement that it serves educational questions rather than live-inventory needs also separates it from the listing and bike-search siblings.

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?

It explicitly directs the agent to use the tool for educational questions that do not need live inventory and supplies two representative queries. It does not name an alternative for inventory searches or disambiguate the sizing example from get_size_guide, so sibling routing is not fully explicit.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, non-open-world operation. The description adds meaningful behavioral context beyond that: the data source is Cyclesite's measured UK used-price data, and the ranking metric is percent retained vs new RRP.

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 front-loaded with the core behavior, then the return shape, then a concrete example. It is three compact sentences with no redundant or filler content.

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?

For a simple read-only ranking tool with an output schema and safety annotations, the description supplies the essential context: data source, metric, and top-N behavior. Minor gaps around explicit sort semantics remain, but the agent has enough to call it correctly.

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 50%: limit is documented in the schema, while sort has only enum values 'best' and 'worst'. The description adds the meaning of 'top N' and the retention metric, but it does not explicitly describe the sort parameter's effect or defaults, so it is adequate rather than rich.

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 specifically states that the tool ranks brands by value retention using measured UK used-price data and returns top N brands by percent retained vs new RRP. This is clear and distinct in practice, but it does not explicitly differentiate itself from siblings such as get_price_trends or get_valuation.

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 example question ('which bike brands hold their value best?') implies the intended use case. However, the description gives no explicit when-not-to-use guidance or alternatives, so the agent must infer competitive fit against sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds genuinely non-obvious behavior: contact only via `howToContactSeller`, delivery terms limited to `delivery.summary`, and the explicit warning that no price or delivery has been agreed through this tool — valuable anti-hallucination framing. It does not say what happens when a slug is stale or the listing is removed, which is the main remaining gap.

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?

Front-loaded with the resource and returned fields, then the parameter source, then a usage example, then behavioral caveats — a sensible ordering. The final sentence is longer than strictly necessary and packs three distinct constraints together, but each one carries real disambiguation value.

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-value documentation is not required, yet the description still orients the agent by naming the main field groups. Combined with the marketplace-vs-seller caveats, it covers everything needed to call correctly. Only the missing note on invalid or delisted slugs keeps it from a 5.

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 coverage is 100% with a single required `slug` parameter already documented with an example format, so the baseline is 3. The description adds only the provenance note that the slug comes from a listing result, which is modest added meaning rather than format or validation detail.

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 ("Full details for a specific bike listing on Cyclesite") and enumerates the content returned: specs, condition, frame number presence, photos, delivery, seller's city. This clearly separates it from siblings like search_bikes, get_spec_sheet, or get_model_info, which do not return a single listing's full record.

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?

"Takes the URL slug from a listing result" tells the agent the precondition and where the identifier comes from, and the example utterance ("tell me more about that 2022 Trek Domane") shows the triggering conversational context. It lacks explicit when-not-to-use guidance, e.g. pointing to get_spec_sheet or get_model_info when the user wants model-level rather than listing-level data.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value on top: what the composite is made of and that it is refreshed nightly, which tells the agent about data freshness. It does not say whether the signal is cached, scoped by region, or how strong the buy/sell verdict is presented, so it is good but not exhaustive.

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 compact sentences, front-loaded with the core verdict-first framing, then the composite inputs, then an example and refresh cadence. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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-format detail is rightly omitted, and the description covers scope, inputs to the metric, and freshness. The only gap is the unresolved tension between the bike-specific example and the parameterless market-wide scope, which could cause an agent to over-promise specificity to the user.

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?

With zero parameters, the baseline is 4; the description correctly implies a market-wide aggregate with no filtering by bike, brand, or category. The example question ('is now a good time to buy a road bike?') is slightly at odds with a parameterless, market-wide tool, which is the one ambiguity left unaddressed.

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 a specific resource and output: a buyer's-vs-seller's market composite for the UK used-bike market, built from days-to-sell, asking-vs-sold spread, and inventory levels. That clearly separates it from data-dump siblings like get_market_index and get_price_trends, though it never names those siblings explicitly to route the agent.

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?

It gives a concrete when-to-use trigger ("should the user buy or sell now?") plus a sample user utterance, which is enough for an agent to match intent. It stops short of stating exclusions — e.g. that per-model pricing questions belong to get_valuation or get_price_trends.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the data is a nightly-refreshed index sourced from real UK market prices, and results are aggregated per category. The only gap is that freshness/aggregation mechanics (e.g. how recent the underlying sample is) are not spelled out, which is minor given the output schema.

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?

Front-loaded with the core fact (what data, what granularity) before the example, and compact overall. The closing sentence ('Refreshed nightly from real UK market prices') largely restates the earlier 'nightly index' claim, so one of the four sentences is close to redundant.

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?

With zero parameters, full annotation coverage and an output schema, the description only needs to establish scope and freshness, which it does. The one remaining ambiguity is how this snapshot differs from the sibling trend and market-health tools over time, which the description leaves to inference.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The mention of categories (road, mtb, gravel, e-bike) usefully signals that category filtering is not a parameter but a dimension of the returned data, which prevents a wasted attempt to pass one.

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: current UK used-bike market prices by category, with the exact return shape (median + range per category). An agent can distinguish it from per-bike tools like get_valuation or get_depreciation because it is explicitly a category-level snapshot. It does not, however, name or exclude the closest siblings (get_market_health, get_price_trends), so differentiation is inferred rather than stated.

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 example question ('how does the UK used-bike market look right now?') implies when to reach for this tool, which is real but indirect guidance. There is no explicit statement of when to use get_price_trends or get_market_health instead, nor any prerequisite or exclusion.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive lookup. The description adds useful context that it is reference data refreshed when models are added or specs change, but it does not cover behavior for unknown brands/models, case sensitivity, or matching expectations.

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 compact and front-loads the core purpose before listing return fields and giving an example. Every sentence serves a clear role with no unnecessary wording.

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 the description does not need to explain return values in detail, and the listed return fields are helpful. But for a lookup with 0% parameter schema coverage, it is incomplete regarding exact matching semantics and sibling boundaries, especially against get_spec_sheet.

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 must carry the burden of explaining the two required string parameters. It only says 'brand+model', and the example shows spelling like 'Specialized'/'Allez', but it gives no guidance on canonical naming, variants, case handling, or whether brand values must come from list_brands.

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 what the tool returns for a brand+model: category, year range, description, key specs, and market summary. The example reinforces the lookup purpose. However, it does not distinguish itself from siblings such as get_spec_sheet, list_models_for_brand, or compare_bikes.

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?

Usage is implied by the example 'tell me about the Specialized Allez', suggesting a single-model lookup. There is no explicit guidance on when to use this versus list_models_for_brand, get_spec_sheet, search_bikes, or compare_bikes, and no exclusions or prerequisites are stated.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the bar is lower. The description still adds real behavior beyond them: default ordering (newest first), the per-enquiry fields returned (id, listing, latest message, unread count, replied flag), and the required OAuth scope `listings:read`.

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?

Four sentences, front-loaded with the core purpose and ordering, then the entity shape, then the auth requirement and a concrete example. Nothing is padded, though the example sentence is the most expendable line.

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 explained, yet the description still sketches the enquiry shape. With only two optional, fully-documented parameters, the read-only annotation set, and the OAuth scope called out, an agent has everything needed to call this correctly.

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% and both parameters are documented in the schema, so the baseline is 3. The description adds no parameter meaning of its own — it never mentions the limit or the listingId filter, so an agent reading only the description would not know it can narrow results to one listing.

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 a specific verb and resource ('Show the messages buyers have sent about the authenticated user's Cyclesite listings') plus ordering ('newest first') and the entity's shape. It implicitly separates enquiries from other message types, but never names the sibling get_my_messages, so the agent must still infer which of the two message tools to pick.

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?

Usage is conveyed by example ('any messages about my Trek?') and by the note that the seller can answer an enquiry by its id, which points toward respond_to_enquiry. There is no explicit when-not guidance and no sibling tool is named, so the routing decision is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new operational context: the required OAuth scope `listings:read`, which an agent must know before calling and which appears nowhere in the schema.

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?

Content is front-loaded with the core purpose, then modes, then auth requirement, then an example. Four sentences with little waste, though the enquiries sentence is redundant-adjacent and slightly muddy.

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?

With an output schema present, return values need no explanation, and annotations plus full schema coverage carry much of the burden. The description fills the remaining gaps (scope, mode behavior, auth) but leaves the relationship to get_my_enquiries unresolved, which matters given a 32-tool sibling set.

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 both parameters are already documented, including 'Omit to list all threads.' The description restates the threadId mode-switch semantics without adding format or edge-case detail, and never mentions the limit parameter or its 1-50 range. Baseline 3 for a fully documented schema.

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 names a specific verb and resource ('Read the buyer's own Cyclesite message threads and any seller replies') and scopes it to the buyer's side, so it is distinguishable from seller-side tools like respond_to_enquiry. However, it does not explicitly distinguish itself from get_my_enquiries, and the line 'Enquiries the buyer has sent to sellers appear here' blurs rather than sharpens that boundary.

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?

It gives clear conditional usage: no arguments lists all conversations, a threadId returns that thread's messages, plus a concrete triggering utterance. It stops short of naming an alternative tool or stating when not to use it, which is why it is not a 5.

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

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

The annotations already declare read-only, idempotent, closed-world, and non-destructive behavior. The description adds useful context beyond annotations: the data is monthly, refreshed at month-end, and sourced from Cyclesite's index series. It does not describe coverage limitations, but with annotations carrying the safety profile, a 4 is appropriate.

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 short sentences front-load the scope, then give a concrete example and refresh cadence. There is no repetition or filler, and every sentence adds useful 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?

This is a simple two-parameter read-only tool, and the output schema exists, so return values need not be described. However, the description omits valid category values and default behavior when optional parameters are not supplied, leaving meaningful invocation gaps.

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 coverage is 50%: months has a range in the schema, while category is undocumented. The description clarifies that months means a lookback and category means bike category (with a road-bike example), but it does not enumerate valid categories or state defaults when optional parameters are omitted.

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 a specific resource (UK used-bike price trends), scope (last N months, by category), and source (Cyclesite index series). It is clear, but it does not explicitly differentiate from nearby siblings such as get_market_index or get_depreciation, so it falls short of a 5.

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?

An example question signals a typical use case, but there is no explicit when-not guidance or named alternative among siblings. The monthly-refresh note adds context but does not help the agent choose between this tool and related market tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the description needn't repeat safety. It adds genuinely new operational facts: a 15-minute refresh cadence, live data, UK-only scope, active listings only, and a hard 10-result ceiling. It says nothing about empty-result behavior or pagination, but the output schema covers the response shape.

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?

Front-loaded with the core fact (fresh active listings, cap, cadence), then use cases, then filters. Slight redundancy between 'refreshed every 15 minutes' and the trailing 'Live data,' which could be dropped.

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?

For a zero-required-parameter browse tool with annotations and an output schema, the description covers freshness, geography, active-only scope, the result cap, and intended question types. Only edge behavior (no results, how 'freshest' is ordered) is left unstated.

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 coverage is 67%: limit and maxPrice are already documented (including the 1-10 range and GBP), and category is self-describing through its enum. The description only adds that both filters are optional and that the result set is capped at 10, which is marginal value over the schema.

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 resource and scope: 'up to 10 of the freshest active UK listings, refreshed every 15 minutes.' It also contrasts itself against filter-driven browsing ('rather than a specific filter'), which is enough for an agent to choose between this and the search/search_bikes family.

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?

Gives concrete when-to-use examples ('what's new today?', 'any new road bikes this week?') and an explicit when-not ('rather than a specific filter'). It stops short of naming the alternative tool to use instead, so routing still requires a small inference.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so the description earns credit for the extras: the methodology (height to inside leg to seat tube), the fact that results are refined with real listing data, and that children are sized by wheel diameter with the tool stating this in its output. It does not discuss caching or data-freshness limits, so not a 5.

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 core purpose is front-loaded in the opening clause and the example anchors it at the end. The first sentence is long with several stacked clauses, but every clause adds information rather than repeating 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?

With annotations and an output schema already in place, the description covers purpose, method, and the kids edge case, which is what an agent needs to call it. The notable gap is the optional `category` parameter: nothing says what the tool assumes when only heightCm is supplied.

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 coverage is only 50% — heightCm has a range description but the 16-value category enum is undocumented. The description maps both inputs conceptually (height, bike category) and usefully flags that for children the height path is replaced by wheel diameter, but it never explains enum values, what 'other' does, or what happens when category is omitted.

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: a frame-size recommendation derived from rider height and bike category, with the exact chart lineage (height to inside leg to seat tube) and the data source (UK listing data). This clearly separates it from siblings like get_spec_sheet (geometry lookup) and recommend_bike_for_budget (budget-based recommendation).

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 ("I'm 178cm — what road-bike size do I need?") gives an unambiguous usage context, and the children note signals the boundary case where height is not the right input. No explicit when-not guidance or named alternative sibling is provided, so it falls short of a 5.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description's added value is the 'most-common' aggregation semantics — this returns a typical/derived value rather than a single authoritative record — plus the dual data sources. It doesn't discuss coverage gaps (e.g., missing year, sparse inventory) but adds real context beyond the annotations.

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?

Front-loaded with what the tool returns, followed by the returned fields and a compact usage example. Two sentences plus an example, with essentially no wasted wording; the field list is close to redundant with the output schema but still orienting.

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?

For a simple three-parameter, read-only lookup with an output schema and full annotation coverage, the description is largely sufficient: it explains the derivation, the aggregation behavior, and the e-bike special case. Only the lack of sibling differentiation and parameter naming conventions leaves a small gap.

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 must compensate. It does communicate that year is optional and acts as a narrowing qualifier (bracketed [+year]) and that brand+model identify the bike, but it gives no format guidance (e.g., exact model naming) for the three parameters.

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 concrete resource (aggregated spec sheet for brand+model[+year]) and its provenance (live UK inventory plus catalogue record). It also enumerates the fields returned, so the agent knows exactly what it gets. It does not explicitly distinguish itself from close siblings like get_model_info or compare_bikes, which keeps it from a 5.

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 example question ('what groupset does a Canyon Endurace usually have?') implies the intended use case well. However, there is no explicit when-to-use/when-not guidance and no mention of when to prefer get_model_info, compare_bikes, or search_bikes instead.

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

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

The annotations handle the safety profile (read-only, idempotent, closed-world), so the description only needs to add context — and it does, disclosing provenance ('real UK sold prices') and freshness ('refreshed nightly'), plus the fallback behavior when a year cannot be resolved. Return format is partly covered but the 'could not be resolved' wording versus a real error is not clarified.

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 core answer is front-loaded in the first sentence and the example at the end anchors usage. Some slack exists — 'Cyclesite's flagship tool' is marketing filler and the year behavior is stated twice, once in prose and once in the 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?

For a simple three-parameter read tool with an output schema and full annotations, the description covers purpose, freshness, and year handling adequately. The remaining material gap is how to construct `brand` and `model` strings correctly, which is the most likely failure mode given only 33% schema coverage.

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 coverage is only 33%: `year` is well documented in the schema and the description largely restates that behavior, while `brand` and `model` are bare strings with no format or matching rules anywhere. The description does not compensate for that gap — an agent still does not know whether brand must match list_brands output exactly.

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 a concrete verb and resource — returning what a used UK bike is worth — and enumerates the payload (median, range, year curve, confidence, comparables). That scope implicitly separates it from siblings like get_depreciation and get_price_trends, though no sibling is named explicitly.

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 closing example ('what's a 2022 Trek Domane SL 6 worth?') gives a clear usage context, and the `year` paragraph explains when to supply a year versus omitting it. There is no explicit when-not-to-use guidance or naming of nearby alternatives such as suggest_listing_price.

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

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

Beyond the annotations' read-only, non-destructive safety profile, the description discloses the capped wins and flags and the deliberate omission of the underlying score to discourage gaming. This is useful behavioral context, though it says nothing about the grading criteria or whether the grade can change as listing data changes.

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 compact and front-loaded with the tool's output, then efficiently covers audiences, an example request, and the important score limitation. Each sentence contributes distinct information without unnecessary wording.

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?

For a simple one-parameter read operation with an output schema, the description supplies enough information to understand and generally invoke the tool correctly. Its main remaining gaps are slug acquisition or format and limited guidance about grading criteria or sibling-tool selection.

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%, and the description only says to "provide the slug." That confirms which input to supply but adds no slug format, example value, or guidance on obtaining it from another listing tool.

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 identifies the resource and result: a categorical quality grade for a Cyclesite listing, accompanied by up to two wins and two flags. The categorical-versus-numeric distinction clarifies its scope, although it does not explicitly differentiate the tool from siblings such as get_listing_detail or check_stolen.

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?

It gives two concrete use cases—buyer trustworthiness assessment and seller self-audit—and includes an example buyer question with the required invocation input. It does not name alternative tools for raw listing details, theft checks, or numerical valuations.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: results are ordered by stock level and inventory is only exposed as coarse bands (none / 1-5 / 6-25 / 26-100 / 100+), which warns the agent not to expect precise counts.

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?

Purpose and stock-band caveat are front-loaded, and the example earns its place by showing a realistic invocation. The opening sentence is long and slightly run-on, but there is little waste.

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?

With an output schema present and full parameter documentation, the description only needs to frame scope and any surprising return semantics, which the stock-band explanation does. Nothing essential for a correct call is missing.

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 q/limit/offset semantics are already documented in the schema. The description only gestures at paging and name-checking, adding no syntax or format detail beyond the schema; baseline 3 applies.

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 ('Paginated UK bike-brand catalogue from Cyclesite'), plus ordering by stock level and domain scope. That is enough to tell it apart from list_models_for_brand, which returns models within a brand rather than the brands themselves.

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?

Gives clear usage contexts (checking a brand name, listing options, paging through the catalogue) and an example question that makes the intended call obvious. It does not explicitly name a sibling as the alternative or state when not to use it.

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

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

The annotations already establish a safe, read-only, idempotent operation, while the description adds that results are paginated and summarizes their contents. It provides no further behavioral context such as result ordering, empty-result behavior, or how pagination interacts with filtered results.

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 compact and front-loaded, giving scope and pagination first, then result contents, then a concrete example. Every statement contributes useful selection or invocation information without filler.

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?

For a simple read-only list operation with four parameters, clear annotations, and an output schema, the description supplies sufficient scope and a workable invocation example. Its principal remaining gap is explicit routing guidance among nearby brand, model-detail, and bike-search siblings.

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 example maps brandSlug to "trek" and category to "road", making the two filtering inputs easy to invoke together. However, this largely restates information available from the schema, and mentioning pagination adds only general context for the already-documented limit and offset parameters.

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 scopes the operation to models for a single brand on Cyclesite and identifies the returned model names, year ranges, and in-stock flag. The Trek road-bike example makes the purpose concrete, but there is no explicit differentiation from list_brands, get_model_info, or search_bikes.

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 example question, "what Trek road bikes are available?", provides clear usage context and demonstrates brand and category filtering. It does not explain when an agent should instead use a broader search tool or a model-detail tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely non-redundant behavioral fact: the required OAuth scope `listings:read`, which an agent must satisfy before calling. It does not disclose pagination or default-result behavior, keeping it from a 5.

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 short sentences, front-loaded with purpose, then the auth prerequisite, then a usage example — no wasted wording. The example sentence is mildly redundant with the purpose statement but serves as a routing hint.

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?

With an output schema present, return values need no explanation, and the annotations carry the safety profile; the description supplies purpose, scope, and auth requirements. The remaining gaps — default status behavior and page size handling — are minor for a zero-required-parameter list 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?

Schema description coverage is only 50%, and the description partially compensates by naming the three status values, though it omits the 'all' enum member actually present in the schema. It says nothing about the `limit` parameter or default values, so it does not fully close the coverage gap.

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 uses a specific verb and resource — 'Show the authenticated user's Cyclesite listings' — which clearly scopes the call to the caller's own data, distinguishing it from siblings like get_recent_listings or search. It also enumerates the status buckets (draft / active / sold). It stops short of naming an explicit sibling it is not, so a 4 rather than a 5.

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?

Usage context is implied through the example utterance ('how are my listings doing?') and the OAuth scope requirement, so an agent can infer this is the self-scoped listing tool. There is no explicit when-not guidance and no named alternative for browsing other sellers' listings.

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

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

Beyond the annotations, the description discloses real side effects: the message lands in the buyer's Cyclesite inbox, the seller is notified, and a per-buyer-per-listing 2/day rate limit applies. It also flags the OAuth scope `enquiries:respond`, which is valuable since the scope name is misleadingly shared with seller replies. It does not explain the irreversibility implied by destructiveHint=true (that a sent enquiry cannot be unsent).

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 key fact (what it does) is front-loaded, followed by delivery behavior, limits, auth, and an example in a sensible order. The example sentence is long but earns its place by demonstrating message composition; no filler sentences.

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?

For a two-parameter mutation with an output schema, the description covers everything an agent needs: destination, notification behavior, rate limit, required auth scope, and message content guidance. Return values need not be described because an output schema exists.

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 coverage is 100%, so the baseline would be 3, but the example adds genuine meaning about what belongs in `message` — a compound question about service history and collection logistics. `listingId` gets no added semantics beyond the schema's own description.

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 and resource ('Send an enquiry to a Cyclesite seller') and names the acting party ('on the buyer's behalf'). It does not explicitly name the sibling it is not (respond_to_enquiry, get_my_enquiries), so differentiation is only implied by the note that the scope is 'shared with seller-side replies'.

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?

It gives a concrete usage example ('message the seller of that Trek and ask whether it has had a service...') and states a hard daily cap of 2 per buyer per listing, which tells the agent when this is viable. It stops short of explicit exclusions — nothing says to use respond_to_enquiry for seller-side replies or get_my_enquiries to read answers.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds a genuinely non-structured fact, the required OAuth scope `listings:manage`, which an agent needs before attempting the call. It stops short of saying whether the change is reversible or what happens to open enquiries.

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?

Two sentences and a short example, front-loaded with the core action before the optional detail. The example earns its place by demonstrating how free-form user phrasing maps onto the price, venue and date parameters.

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 and rich annotations exist, so return values and safety hints need not be restated. The description covers auth scope, optional fields and input shape; only post-sale side effects (impact on reservations, enquiries, listing visibility) are left 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 coverage is 75%, with only listingId undocumented. The description names the three optional values (price, venue, date) but adds little syntax beyond the schema; the one useful extra is the 'last Saturday' phrasing, which signals that relative dates are acceptable input and must be resolved to YYYY-MM-DD.

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 gives a specific verb and resource ('Mark a Cyclesite listing as sold') plus the optional attributes that can be captured. It is clearly distinct from siblings such as reserve_listing or publish_listing by implication, though it never names them.

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?

Usage context is implied through the natural-language example and the required OAuth scope, which tells the agent the caller must hold `listings:manage`. There is no explicit guidance on when to prefer this over reserve_listing or how to handle a listing that is already reserved or sold.

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

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

Annotations already declare idempotentHint, destructiveHint and openWorldHint, but the description adds substantial context beyond them: the multi-step state machine, the OAuth scope requirement, the free-vs-paid branch, and the confirmation email with a 24h undo link (which mitigates the destructive hint). It doesn't state what happens to the draft if the user abandons the flow or whether a re-publish overwrites a live listing.

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?

Front-loads purpose, then the call sequence, then constraints and the scope requirement, in six tight sentences with no filler. The final intent example ('sell my Trek Domane') earns its place by giving the agent a matching phrase for tool selection.

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 output schema exists and the description rightly summarizes its step values rather than restating return shapes, and the multi-step flow is fully traceable. The notable omission is that with 0 required parameters across 24 fields, the description never says what minimum set of fields a first call needs, which is the main decision an agent faces here.

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?

Draft-level semantics matter most and are covered: draftId is explained as the resumption token from a prior call, and the 3+ photo threshold is a behavioral rule the schema can't express. With 24 parameters at 54% coverage, roughly a dozen fields (brand, model, year, priceGbp, willShip, groupset, knownIssues, frameSize) are undocumented in both schema and description, so the gap is only partly compensated.

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 ("Publish a Cyclesite listing on the user's behalf") and immediately disambiguates it from draft_listing by describing the publish-then-photo-then-live lifecycle. An agent can tell what this does and roughly where it sits in the flow without opening the 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?

Gives clear conditional usage: call with no draftId first, then re-call with the same draftId as photos are uploaded, and the call resolves to 'live' or 'payment_required'. It never explicitly names a sibling alternative (e.g. draft_listing for staging, check_stolen for the serial check) or says when not to call it, so it stops short of full routing guidance.

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

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

Beyond the read-only and idempotent annotations, it discloses the live-inventory scope, a non-obvious preference for higher-engagement listings, and rationale-bearing recommendations. However, "Returns up to 5 picks" is only consistent with the default because the limit parameter permits values up to 10.

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 opening sentence front-loads the resource, scope, and main inputs, followed by compact ranking and output details. The three examples illustrate meaningfully different requests without filler or unnecessary repetition.

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?

Together with the rich input schema and output schema, the description provides enough information for a normal recommendation call and explains its curation bias. Explicit alternatives to broad search tools and an accurate statement of the configurable result limit would make it fully complete.

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?

With 80% schema coverage, most parameters are already documented, while category is largely self-describing through its enum. The examples reinforce how budget, city, and intent combine, but add little parameter syntax or mapping guidance beyond the schema.

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 identifies the operation as curated bike recommendations from Cyclesite's live UK inventory, constrained by budget and intent. The engagement preference and per-pick rationale further distinguish it from raw listing-retrieval siblings such as search_bikes and get_recent_listings.

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 budget-and-intent framing and three concrete example requests make appropriate scenarios clear, including road, e-MTB, and commuting recommendations. It does not explicitly say when to use search or search_bikes instead for exhaustive or directly filtered results, so sibling routing remains implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the concrete return payload (5-step checklist + official report URL) and the jurisdictional scope (UK). It doesn't mention whether the optional bike details personalize the output, but that is a minor gap given the annotations.

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?

Two compact sentences with the purpose front-loaded, followed by the return contract and a representative user utterance. Slight redundancy with the title ('How to report a stolen bike') but no wasted prose.

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 needn't be spelled out, yet the description still summarizes them, which helps routing. For a guidance/checklist tool with zero required parameters this is nearly complete; the only real hole is the unexplained optional brand/model/serial inputs.

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% for three parameters (brand, model, serial), so the description carries the full burden and says nothing about them. An agent cannot tell from the text whether supplying serial changes the checklist, whether these are optional context, or what format a serial takes. This is the definition's clearest weakness.

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 a specific verb and resource ('reporting a stolen UK bike') and enumerates the areas covered: police, insurance, listing alerts. It also says exactly what comes back, a 5-step checklist plus the Cyclesite report URL. It never explicitly contrasts itself with siblings such as check_stolen, so it lands at a clear 4 rather than a 5.

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 example query "my bike was just stolen, what do I do?" gives an unambiguous trigger condition, and the UK scope narrows applicability. There is no explicit when-not guidance and no named alternative (e.g. 'use check_stolen to verify whether a serial is already flagged'), which keeps it short of a 5.

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

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

Goes well beyond the annotations: discloses the 24-hour duration, that the hold is free and non-binding on the seller, that no payment or deposit is taken, and the required OAuth scope `listings:manage`. The annotations only declare it a non-destructive, idempotent mutation; the description supplies the consequences and prerequisites an agent actually needs.

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?

Front-loads the action and duration, then caveats, then auth requirement, then an example — a sensible order with no wasted sentences. The payment disclaimer is slightly tangential but has practical value in a buyer-facing conversational context, preventing the agent from promising payment handling.

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?

For a one-parameter tool with an output schema and rich annotations, the description covers prerequisites (scope), semantics (24h, advisory), and trigger phrasing. The only real omission is any detail on the listingId argument or what happens on a repeat call, which idempotentHint already signals.

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 single required parameter `listingId` has no description in the schema (0% coverage), and the description never explains its form or provenance beyond the example reference to 'that Trek'. The name is largely self-explanatory, so this is adequate but not compensating for the coverage gap.

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 with exact scope: 'Hold a Cyclesite listing for 24 hours so other buyers can't claim it.' The temporary, non-exclusive nature of the hold makes it unmistakably distinct from siblings like make_enquiry or save_search.

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?

Usage context is clear from 'while the user decides' and reinforced by a concrete utterance example ('put a hold on that Trek for me, I want to view it Saturday'). It lacks an explicit when-not or a named alternative tool, which keeps it short of a 5.

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

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

Annotations only say destructive/non-idempotent/open-world; the description adds genuinely new behavior: the buyer is notified, the outgoing message is labelled as AI-sent on the seller's behalf, and the required OAuth scope `enquiries:respond`. It stops short of saying duplicate sends produce duplicate notifications, but the side-effect profile is otherwise well disclosed.

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?

Front-loaded with the action, followed by scope, side effects, auth, and a single illustrative example. Every sentence carries information an agent would otherwise have to guess.

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?

For a two-parameter mutation with an output schema, the description covers auth, audience, notification side effect, and AI disclosure. Minor gaps remain around error handling for an invalid or foreign enquiryId.

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 coverage is 100%, so both parameters are already documented. The description reinforces that the enquiryId must belong to the seller and the example implies the answer is natural seller-voiced text, but adds no format, length, or validation detail beyond the schema.

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 ('Send the seller's reply to a buyer who messaged about one of the authenticated user's listings') and pins the scope to the seller's own enquiries, which separates it cleanly from make_enquiry and get_my_enquiries.

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?

Gives a clear context of use plus a realistic example utterance that shows the intended caller flow (find latest enquiry, then reply). It does not explicitly name get_my_enquiries as the way to obtain the enquiryId, so routing is implied rather than stated.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description goes well beyond that by disclosing the side effect (a SavedSearch row is created on the user's account), the required OAuth scope `listings:read`, the delivery mechanism (email on new matching listing or price drop, instant or daily digest per user preferences), and the per-user 50-active-alert cap. These are exactly the operational facts an agent needs before mutating account state.

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 purpose sentence is front-loaded and the parenthetical about read-only data vs. an actual write is a high-value clarification, not filler. The example sentence is the longest element and is only partially earned since the filter fields are already in the schema, but nothing is redundant with the annotations.

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 no explanation, and the description covers the write semantics, auth scope, delivery behavior, and quota for a 9-parameter mutation tool with no required fields. The one gap is the non-idempotency consequence (whether saving the same filter twice creates duplicate alerts), which matters given idempotentHint=false.

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 coverage is only 33% and six parameters (brand, model, minPrice, maxPrice, condition, category) have no schema descriptions, so the description must compensate. The examples implicitly map brand/model/city/price/category onto the filter, and "instantly or in a daily digest" clarifies the alertFrequency intent (which does have a schema description anyway). It still adds no meaning for `name` or for minPrice vs. maxPrice interaction, leaving some of the gap unfilled.

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?

"Subscribe the user to email alerts for Cyclesite listings matching a filter" states a specific verb (subscribe) and resource (saved search alert), and the noun "subscribe" cleanly separates it from the read-only search/search_bikes siblings. An agent can tell this creates a persistent alert rather than running a query.

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 two quoted examples ("let me know when a Trek Domane SL 6 in Manchester under £2,000 appears", "alert me to any e-MTB drops below £2,500 in Yorkshire") make the intended trigger situation concrete, and the 50-alert cap gives a precondition. It stops short of explicitly naming when to prefer this over search_bikes (one-off lookup vs. ongoing monitoring), so the exclusion is inferable rather than stated.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the description is not carrying the safety burden. It adds real context on top: results are restricted to active UK used-bike listings, matching covers title/brand/model, and each returned id is a listing id that can presumably be fed to fetch or get_listing_detail. It stops short of noting result limits, pagination, or ordering.

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?

Four short sentences, front-loaded with the compatibility purpose and then the actual behavior. No filler, though the return-shape sentence partly duplicates the output schema and could have been trimmed.

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 explained, and safety is covered by annotations. The remaining gap is routing: with ~30 siblings including search_bikes, search_by_location and fetch, the description gives no basis for choosing this tool, and says nothing about result caps or paging.

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 coverage is 100% and there is only one parameter, so the baseline would be 3. The description earns above baseline by explaining what the query actually matches against (title, brand, model), which the schema's bare 'Free-text query' does not convey.

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: free-text search over Cyclesite's active UK used-bike listings, with the match fields (title, brand, model) named. It is clear what the tool does, but it never distinguishes itself from the sibling search_bikes, which an agent will inevitably compare it against.

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 opening phrase implies the intended consumer (OpenAI deep-research / company-knowledge integrations), so usage context is inferable. However, there is no explicit when-to-use versus search_bikes, no statement of when this is preferred over fetch or search_by_location, and no exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile carries no burden on the description. The description usefully adds that results are capped at 5 active listings, include specs and URLs, and come from continuously refreshed live data. It stops short of disclosing pagination behaviour, sort order, or what happens with zero matches, which matters for a live-index search returning a small fixed page. The 'openWorldHint: false' annotation sits in mild tension with a live external marketplace, though not enough to call a contradiction.

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 front-loaded with the core purpose, then filters, then return shape and freshness, with example queries at the end. Four short sentences with no filler; the examples earn their place by showing multi-filter composition.

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?

With an output schema present, the description need not explain return values in depth, and it covers result count, contents, and data freshness adequately for an all-optional 6-parameter search. The remaining gap is operational: no mention of pagination, sorting, or empty-result behaviour, which an agent would want for this kind of capped live search.

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% and both enums are self-explanatory, so the schema already does the heavy lifting and baseline 3 applies. The description adds marginal value by mapping natural-language phrasing ('under £2,000', 'near Bristol') onto the price and city parameters, but gives no guidance on default behaviour when filters are omitted or on how city matching works.

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 names a specific verb and resource ('Search live UK used-bike listings on Cyclesite') and enumerates the filterable dimensions, so the agent knows exactly what the tool retrieves. It does not differentiate from sibling tools such as 'search', 'search_by_location', or 'find_similar_listings', which overlap in purpose, leaving the agent to infer which one to pick.

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?

Usage is only implied, through example queries like 'a Trek Domane in Manchester under £2,000' that show how to compose filters. There is no explicit statement of when this tool is preferred over 'search' or 'search_by_location', nor any prerequisite or exclusion guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context: radius capped at 50 miles, results capped at 10 and ordered by distance, distances rounded to the mile, and a searchedFrom field naming the measured place. Some of that overlaps the output schema, which is why it is not a 5.

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?

Front-loads the core purpose, then constraints (postcode handling, radius cap, result cap), then examples — a logical order with little waste. The examples sentence is a mild luxury but does encode valid query shapes.

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?

For a 5-parameter filtered search with annotations and an output schema, the description covers the hard parts an agent would otherwise get wrong: accepted place formats, the no-coordinates rule, radius ceiling and result ceiling. Only the filtering semantics of `category` and `maxPrice` are left to the schema, which is a reasonable division of labor.

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?

Adds meaning beyond the 60%-covered schema: it explains that a full postcode is truncated to its district, that a district like 'BS1' or 'M20' is the expected form for `place`, and that radius is capped at 50 miles. It says nothing about `category` or `maxPrice`, leaving those to the schema.

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+resource ('Find Cyclesite listings') plus a precise geographic scope ('within a radius of a UK town, city or postcode district'). An agent can tell this is a geo-radius listing search, but no sibling such as search_bikes or search is named, so differentiation from keyword search is left implicit.

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?

Gives concrete usage examples ('used bikes within 25 miles of Leicester', 'road bikes near LE10') and an explicit exclusion ('coordinates are not accepted'), which steers the agent away from a common wrong input. It never names an alternative tool for non-geographic searching, so the when-not-to-use-this-tool routing is incomplete.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds non-obvious behavior: the ask is anchored on the model year's own median rather than the all-years median, and the response's `basis` field names what was actually used. That is genuine disclosure beyond the annotations.

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?

Front-loaded with the audience and the three returned numbers, then the data provenance, then the year nuance, then an example. Slightly redundant with the schema's own `year` text, but every sentence is doing work and the example clarifies the natural-language query shape.

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?

With an output schema present and rich annotations, the description need not explain return values or safety, and it covers audience, market scope, inputs and the one surprising behavior (year anchoring). The only gap is that it never signals what to do next after getting a price, e.g. draft_listing or publish_listing.

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 coverage is low at 25% — only `year` is documented, and its schema text already explains the anchoring and `basis` behavior. The description compensates by showing the optional-parameter pattern brand+model[+year][+condition] and that year and condition are optional, but it never says how condition moves the ask, nor explains the six condition enum values.

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 noun and outcome (suggested ask, floor, ceiling) for a named resource (brand+model[+year][+condition]) and scoped market (UK). It also explicitly separates itself from the valuations tool by noting the same data 'framed as seller guidance', which lets an agent tell it apart from get_valuation without reading either 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?

'For a seller about to list' gives a clear triggering context, and the comparison to the valuations tool implies the buyer-side alternative. There is no explicit exclusion ('do not use for buying decisions, use get_valuation') and no mention of follow-on tools like draft_listing or publish_listing, so the routing help stops short of a full when/when-not statement.

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