cyclesite-mcp-server

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

Goes well beyond the annotations (which only cover read-only/open-world/idempotent) by disclosing a per-serial rate limit of 3/hour with the anti-enumeration reason, that data is live, and that multiple registries are cross-referenced on each call. This is exactly the operational context an agent needs to avoid throttling.

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 tight sentences, front-loaded with the core action, followed by data provenance, rate limit, and example. No filler or repetition of 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?

An output schema exists so return values need not be explained, and the description fully covers scope (UK bikes), data provenance, freshness, and the rate constraint. Nothing needed to invoke it correctly 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% so the serial's length bounds are already documented; the description adds marginal value by showing a concrete example serial format ('WTU123456') and tying the parameter to the international registry scope it is checked against.

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 (check) and resource (UK bicycle stolen status) scoped to a serial number, with a concrete worked example. It is clearly distinguishable from the sibling report_stolen, which files rather than queries a report.

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 via the example query and the enumeration rationale, but there is no explicit statement of when to use this vs a sibling like report_stolen or compare_bikes, and no exclusions or prerequisites are given. Adequate but leaves routing 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, openWorldHint, and idempotentHint. The description adds useful behavioral context: it performs a server-side combination of two other tools, returns both spec sheets and valuations, and has a hard limit of 3 bikes. This goes beyond what annotations provide without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus a relevant example. It is front-loaded with the core purpose, then provides the key constraints and an illustrative use case. Every sentence contributes meaning without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential inputs (up to 3 bikes, brand+model+year), what it returns (spec sheets and valuations), and how it works (reusing other tools). With an output schema present, return values need not be explained. Minor gaps like behavior with fewer than 2 bikes or error handling are not critical for a read-only comparison tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema simply defines a 'bikes' array with brand, model, and optional year, but provides no descriptions. The description compensates by explaining each bike is identified by brand+model[+year] and gives an example, making the parameter structure clear. It could be even more explicit about the types, but the example helps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'compare' and the resource 'bikes', with a specific function: side-by-side comparison of up to 3 bikes returning spec sheets and valuations. It distinguishes itself from sibling tools like get_spec_sheet and get_valuation by combining both into one call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when the user needs both specs and valuations together to pick a bike, and explicitly mentions it reuses get_spec_sheet + get_valuation server-side, hinting at alternatives for single lookups. It also gives a concrete example. However, it does not explicitly state when NOT to use it or name alternatives directly.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the description need not repeat those. It adds meaningful context beyond annotations by clarifying that this tool does not publish, is a sell-side helper, and is meant for previewing. This is useful behavioral disclosure not present in the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus an example, with the core purpose stated first and the exclusion of publishing immediately after. No redundant words; every sentence earns its place. The example is illustrative and concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema and annotations cover safety (readOnlyHint), the description is largely complete. It states what it does, what it doesn't do, and gives a concrete use case. It could mention prerequisites (e.g., seller facts are required) but that is implicit from 'turn a seller's raw facts'. Minor gap but not critical.

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 20% (only knownIssues and itemCondition have descriptions). The description does not systematically explain parameters, but the example ('2021 Specialized Allez, very good condition, in Bristol') maps to year, brand, model, condition, and city, giving implicit semantic hints. However, it does not fully compensate for the low schema coverage, so a 3 is appropriate.

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: 'turn a seller's raw facts into a polished Cyclesite listing draft' and enumerates what the draft includes (title, description, suggested price, photo plan). It also explicitly distinguishes itself from publish_listing by noting it does NOT publish, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance: 'Does NOT publish — for actual publication use publish_listing (requires OAuth).' It states the use case (previewing a listing) and names the alternative tool, providing clear when-to-use and when-not-to-use instructions. The example further illustrates the intended invocation.

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 mark this as read-only, open-world, idempotent. The description adds that the text is a plain-prose summary rather than raw structured data, which is a non-obvious behavioral trait. No 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?

Three sentences with no fluff; the first sentence provides context, the second states the action, the third explains the return format. Front-loaded enough.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter, high schema coverage, and existing output schema, the description provides the key additional context (purpose, return semantics, and usage). It's complete for a simple fetch.

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 schema already documents the 'id' parameter with 100% coverage, and the description reinforces it by saying it's returned by the search tool. No additional meaning is added beyond the schema's description, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches the full document for a Cyclesite listing id, and differentiates itself from siblings by highlighting its OpenAI deep-research compatibility and plain-prose summary output. The specific verb 'fetch' plus resource adds clarity.

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 says the id comes from the search tool, implying the prerequisite step. It also frames the use case (deep-research answers, quoting) which serves as a guideline. However, it doesn't explicitly compare to sibling tools like get_listing_detail.

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, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context: it returns up to 5 results, filters to active listings, and explains the weighting logic (same brand or frame size weighted higher). This goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no waste. The core behavior and criteria are front-loaded, the usage trigger is stated, and the example is illustrative without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers what the tool does, when to use it, and key behavioral constraints (active listings, up to 5 results, weighting). An output schema exists, so return values don't need to be described. Minor gap: it doesn't mention error behavior for invalid slugs, but this is not critical for a read-only lookup 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 coverage is 100% and the single parameter 'slug' is described as 'Source listing URL slug.' The description adds the semantic context that the slug identifies a Cyclesite listing, but the schema already fully documents the parameter. Baseline 3 is appropriate.

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 ('find'), a resource ('similar active listings'), and precise criteria (same category, ±25% price, brand/frame size weighting). It also gives a concrete example of when to use it, which clearly distinguishes it from siblings like search or 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 description explicitly says 'Use when the user is interested in one bike and wants alternatives' and provides an example utterance. This gives clear context for when to invoke this tool versus alternatives like search or compare_bikes.

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 indicate readOnly and idempotent behavior. The description adds meaningful behavioral context: returns up to 3 matching guides, lists the fields returned (title, excerpt, difficulty, reading time, URL), and mentions the 24+ articles. This provides transparency about result limits and content type 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?

The description is two sentences plus an example, with all information front-loaded. It efficiently conveys the resource, result format, usage context, and examples without redundancy. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity and the presence of an output schema, the description is complete. It covers purpose, usage, result limits, and return fields. No additional context is needed for an agent to invoke 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?

The input schema already covers both parameters with clear descriptions (query and limit). The description provides example query values but does not add significant semantic meaning beyond the schema. Baseline of 3 is appropriate given 100% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches Cyclesite's expert buying guides, a specific resource. It distinguishes this from siblings like get_size_guide or get_spec_sheet by focusing on buying guides with journalistic content. The verb 'search' is specific and the scope is well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use for educational queries that don't need live inventory,' providing clear context and excluding use cases for inventory-based tools. It also gives concrete example queries that illustrate when to use the tool. This effectively guides selection among the sibling tools like search_bikes or get_listing_detail.

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 openWorldHint, so the safety profile is established. The description adds context about the data source (Cyclesite UK used-price data) and the ranking metric (% retained vs new RRP), but does not disclose potential edge cases such as data freshness or empty results. This meets the minimal bar given annotations but does not go beyond.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus an example, with no redundant wording. It front-loads the core purpose, then specifies the metric and provides a concrete query. Every sentence contributes 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?

Given the presence of an output schema (which explains return values), the description covers the necessary ground: purpose, data source, metric, and example. It does not explicitly mention the sort parameter, but the schema provides the enum, and the description implies both directions. Overall, it is nearly complete for a simple read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description says "how well (or poorly) they hold their value," which maps to the sort parameter's best/worst enum and adds meaning beyond the raw schema. The phrase "top N" aligns with the limit parameter, which already has a schema description. It partially compensates for the 50% schema coverage by clarifying the ranking direction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: ranks brands by value retention using UK used-price data, and returns top N by % retained vs new RRP. It distinguishes itself from sibling tools by focusing specifically on depreciation, and the example query reinforces its purpose.

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 "which bike brands hold their value best?" provides a clear usage context. It implies when to use the tool, but does not explicitly mention alternatives or exclusions. Still, the context is unambiguous enough for an agent to select it appropriately.

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, openWorldHint, and idempotentHint, covering safety and side-effect expectations. The description adds valuable behavioral context by listing the data fields returned and emphasizing the dependency on a slug from a prior search, which goes beyond what annotations provide.

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 exactly two sentences: the first front-loads the purpose and content, the second gives usage instructions. There is no redundancy or fluff; every word contributes to the agent's understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, output schema present), the description covers purpose, input source, and an example in sufficient detail. It does not need to describe return values since an output schema exists, and it fully supports tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents the slug parameter with an example format, so baseline is 3. The description enhances this by explaining the slug's origin (from search_bikes or get_recent_listings) and providing a conversational use case, adding meaning that the schema 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?

The description clearly states it retrieves full details for a specific bike listing, enumerating the included fields (specs, condition, frame number presence, photos, delivery, seller's city). It distinguishes itself from listing search tools by requiring a slug from a prior search, making its purpose unambiguous and distinct from siblings like get_recent_listings 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 description explicitly explains when to use the tool: when a user wants more details on a listing, and provides the exact source of the required parameter ('URL slug returned by search_bikes or get_recent_listings'). It includes a concrete conversational example, making the invocation context clear.

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 openWorldHint. The description adds valuable context beyond annotations: it explains the tool is a composite indicator of days-to-sell, asking-vs-sold price spread, and inventory levels, and notes that it is refreshed nightly. This enriches the agent's understanding of what the signal represents and its freshness.

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 three tight sentences: purpose, composition, and example+refresh cadence. Every sentence adds distinct value, with no redundancy or filler. The structure front-loads the key question (buy or sell) and then elaborates efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and an output schema exists, the description is complete for selection and invocation: it specifies the market (UK used-bike), the composite nature, the example use case, and the refresh schedule. It covers both what the signal is and how to think about it, with no outstanding 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?

The tool has zero parameters, so the description has no parameter details to explain—it fully captures the tool's meaning and behavior. The baseline for zero-parameter tools is 4, and the description earns that by clearly explaining the tool's output significance without needing param-centric 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?

The description clearly states the tool's purpose: providing a buyer's-vs-seller's market signal for the UK used-bike market, with a specific composite indicator. It includes an example question ('is now a good time to buy a road bike?') that clarifies intended use, and the phrasing distinguishes it from sibling tools like get_market_index or get_price_trends by focusing on the buy/sell recommendation angle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: when assessing whether to buy or sell now, with a concrete example. It does not explicitly name alternative tools or exclusion criteria, but the context is unambiguous enough for an agent to select it appropriately among peers.

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 (readOnlyHint, openWorldHint, idempotentHint), the description discloses the data source ('Cyclesite's nightly index'), refresh cadence ('refreshed nightly'), and return shape ('median + range per category'). This adds meaningful behavioral context without contradicting 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?

The description is three sentences, front-loaded with the core purpose, and includes a practical example query. Every sentence adds value 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 parameterless read-only tool with an output schema, the description is complete. It explains what data is returned, from where, how often it updates, and provides an example. No significant gaps remain.

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 has zero parameters, so the baseline is 4. The description does not need to explain parameters but adds semantic context about the output categories and data freshness, which helps set expectations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports current UK used-bike market prices by category, with specific example categories (road, mtb, gravel, e-bike). It uses a specific verb ('get') and resource ('market index') and is distinguishable from sibling tools like get_market_health or get_price_trends by focusing on current snapshot prices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear use case with an example query ('how does the UK used-bike market look right now?'), implying when to use it. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it for current market price queries.

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 indicate readOnly, openWorld, and idempotent behavior. The description adds valuable context about freshness ('refreshed when models are added or specs change') and that the description is AI-generated, which helps the agent understand content expectations and potential staleness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two substantive sentences plus an example. It front-loads the core purpose, lists the return fields, adds refresh behavior, and gives a natural-language usage example without any 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?

Given this is a simple two-parameter read-only lookup with a rich output schema and strong annotations, the description is complete. It covers the data content, reference nature, and an example, while the output schema handles return structure details.

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 schema has only bare string types with no descriptions (0% coverage). The description partially compensates by specifying 'brand+model' and providing an example, but it does not elaborate on expected format, variants, or edge cases.

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 that this tool returns a Cyclesite catalogue entry for a brand/model and enumerates the included fields: category, year range, AI-generated description, key specs, and market summary. This distinguishes it from sibling tools like get_spec_sheet or get_valuation by centering on a general catalogue overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context through the example 'tell me about the Specialized Allez' and notes that it is reference data refreshed when models/specs change, implying a general lookup. However, it does not explicitly name alternatives or state when not to use this tool relative to its siblings.

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 openWorldHint, so the safety profile is well covered. The description adds meaningful context by disclosing the OAuth scope requirement and the authenticated-user scope, which are not present in 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?

The description is two concise sentences that front-load the core action and resource. The example adds practical clarity without any redundant or verbose 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 tool with an output schema and strong annotations, the description covers the essential purpose, auth requirement, and an example. It could explain how listingId filters results, but the output schema and parameter names largely fill that 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?

The input schema has only 50% coverage, with `listingId` lacking any description. The tool description does not mention either `limit` or `listingId`, so it does not compensate for the missing schema detail. While the parameter names are self-explanatory, the description adds no semantic value to them.

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 ('Show') and identifies the exact resource ('buyer enquiries on the authenticated user's Cyclesite listings'), which clearly distinguishes it from sibling tools like get_my_messages. The natural-language example further clarifies the intended use case.

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 provides clear context by specifying the OAuth scope and tying the tool to the authenticated user's listings. However, it does not explicitly contrast with alternatives (e.g., get_my_messages) or state when not to use this tool, so it stops 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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds the OAuth scope requirement and clarifies the relationship with make_enquiry, which is useful behavioral context beyond the structured data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with the main verb+resource first, followed by usage, pairing, auth, and an example. No wasted words; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the tool is simple, the description covers purpose, usage modes, auth, and a concrete example. No significant gaps remain for a getter 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 100%, so the schema already explains both parameters. The description adds minimal extra meaning beyond saying 'pass a threadId' and 'no args', which is already implied. Baseline 3 is appropriate.

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?

Clearly states the tool reads the buyer's own message threads and seller replies, distinguishing it from sibling tools like get_my_enquiries and respond_to_enquiry. The example reinforces the purpose.

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?

Provides clear context: call with no args to list threads, pass a threadId to read one thread. It also pairs with make_enquiry, but does not explicitly state when not to use it or name alternatives, 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 read-only and idempotent hints. The description adds valuable behavioral context: data is monthly, refreshed at month-end, and sourced from Cyclesite's index. This tells the agent about data freshness and provenance, going beyond the structured 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 sentences, front-loaded with the core purpose followed by a concrete example. No redundant or filler content. Every sentence contributes to understanding the tool's function and usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, the presence of an output schema, and annotations, the description covers the essential scope, data source, and refresh cadence. It does not list all categories, but this is not critical given the schema and example. The description is adequate for a read-only query 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 50% (only months has a description). The tool description clarifies that 'months' means number of months and provides an example category ('road-bike'), but does not enumerate valid categories. It partially compensates for the missing schema description but leaves category values undocumented.

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?

Description clearly states it returns UK used-bike price trends over the last N months by category, with a specific data source (Cyclesite's index series). The example query clarifies the intended use case. This distinguishes it from sibling tools like get_market_health or get_depreciation by focusing specifically on price trends over time.

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 'how have road-bike prices changed in 2026?' implies usage for historical price trend questions, but no explicit guidance on when to use this versus alternatives like get_depreciation or get_valuation. No exclusion criteria or alternative tool references are provided, so usage is only implied.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavior beyond that: 'refreshed every 15 minutes,' 'active UK listings,' and 'live data,' which help the agent understand freshness and scope. No contradiction with 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?

Three short sentences front-load the core value proposition, then give usage guidance, then mention filters. Every sentence earns its place; 'Live data' slightly overlaps with the refresh cadence but is not distracting.

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 read-only browsing tool with an output schema and strong annotations, the description covers selection cues, scope, freshness, and optional filters. The agent has enough context to know when to invoke it and what parameters to consider.

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 schema already documents limit and maxPrice, and category is a self-explanatory enum. With 67% schema description coverage, the description only adds that category and maxPrice are optional filters, which is helpful but does not substantially expand parameter meaning.

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 exactly what the tool returns: up to 10 of the freshest active UK listings, refreshed every 15 minutes. It also distinguishes this from filtered search by saying 'rather than for a specific filter,' making the tool's role clear against 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 gives explicit query triggers ('what's new today?' or 'any new road bikes this week?') and an explicit when-not-to-use condition ('rather than for a specific filter'). It does not name the alternative sibling tool to use instead, so it stops just 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?

Annotations already declare read-only and idempotent behavior; the description adds valuable behavioral context by referencing the Cycleshire chart, real UK listing data, and the wheel-diameter sizing for children. It does not describe edge cases or how missing data is handled, but the added context is meaningful.

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 is front-loaded and the example is easy to parse. The chart URL, methodology note about inside-leg-to-seat-tube, and UK data refinement are somewhat extra, but they add context without becoming 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?

Given the two-parameter schema and an existing output schema, the description covers the core input semantics, an example, and the children exception. It does not discuss optional categories or odd inputs, but an agent would still be able to determine how to call the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documents heightCm fully and provides category enum values but no description for category, so coverage is partial. The description notes that sizing depends on height and category and that children are sized by wheel diameter, which adds meaning. It still does not elaborate per-category sizing semantics or default behavior when category is absent.

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 immediately identifies a concrete resource: frame-size recommendation based on rider height and bike category. The worked example and the children/wheel-diameter case make it clear and help distinguish it from buy-guide or spec-sheet sibling tools.

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 gives an explicit trigger for when to use the tool, and the children statement establishes a conditional sizing path. It does not explicitly name sibling alternatives or state when not to use this tool, so exclusions are supplied only indirectly.

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, openWorld, and idempotent hints. The description adds valuable behavioral context by disclosing the data sources (Cyclesite's live UK inventory plus catalogue record), the aggregation logic ('most-common'), and the conditional inclusion of motor and battery specs for e-bikes. This goes beyond what annotations provide, warranting a score above baseline.

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 polished sentences: the first defines the tool, the second lists the returns and gives a concrete example. Every phrase adds value, and the information is front-loaded with the tool's purpose. No redundancy or 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?

The description covers the input structure (brand+model+year), the output content (listed specs), data sources, and a use case. It does not discuss what happens when no data is available or how the aggregated results are computed in detail, but an output schema exists and the description is sufficient for the tool's straightforward read-only nature.

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 burden. It does mention 'brand+model[+year]' and uses brackets to indicate optionality of year, plus an example with brand and model. However, it does not elaborate on valid values, formats, or constraints beyond what the schema names/type already conveys, leaving some ambiguity about how to format values (e.g., casing, full names).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: providing an aggregated spec sheet for a brand+model+year combination, and it enumerates the exact attributes returned (frame material, wheel size, groupset, etc.). It distinguishes itself from siblings by emphasizing aggregation from live inventory and catalogue data with an example usage ('what groupset does a Canyon Endurace usually have?').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a clear use case: retrieving typical or most-common specifications for a bike model, as shown by the example. However, it does not explicitly mention when not to use this tool or suggest alternative sibling tools, so it misses the 'explicit exclusions/alternatives' criterion for 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 readOnly/openWorld/idempotent, and the description adds meaningful behavior beyond them: values are based on last-advertised asking prices, not confirmed sale prices, and are refreshed nightly. It also discloses that omitting year gives an all-years median while passing year triggers a year-specific median and confidence interval.

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 dense but well ordered: purpose, outputs, year behavior, data source caveat, then an example. Every sentence adds useful information with no filler or 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?

Given the output schema, annotations, and sibling context, the description is complete enough for an agent to select and call the tool correctly. It covers the core use case, the optional-year nuance, the data freshness and caveat, and provides a concrete example.

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 33%, and the description compensates for the year parameter by explaining how it changes the valuation basis. Brand and model remain bare strings except for the implicit example '2022 Trek Domane SL 6', which suggests the mapping but does not fully document those required 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 opens with a concrete value proposition ('what a used UK bike is worth right now') and enumerates specific outputs (median, range, price-by-model-year curve, confidence level, comparable active listings), so an agent can tell this is a valuation endpoint. It does not explicitly contrast with siblings like get_price_trends or get_depreciation, so it stops just short of full sibling differentiation.

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 clear trigger scenario: a user asks what a used UK bike is worth, with an explicit example query. It also provides conditional guidance on when to pass the optional year parameter. It does not state exclusions or point to alternative sibling tools, but the context is clear enough for correct invocation.

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 provide readOnly/openWorld/idempotent hints. The description adds meaningful behavioral context: returns only the categorical grade, not the underlying score, and deliberately avoids gaming by withholding numeric scores. This goes beyond the annotation hints.

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 concise, front-loaded sentences. The first states the main function, the second identifies user audiences, and the third gives an example and a key limitation. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with an output schema, the description covers the purpose, output structure (wins/flags), and a key design limitation. It does not mention behavior for invalid slugs, but that is not essential given the simplicity.

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 only parameter (slug) is mentioned only as 'provide the slug', which simply restates the schema. With 0% schema description coverage, the description fails to explain what a slug is, its format, or give an example slug value. It does not compensate for the schema 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 clearly states a specific action ('grade') applied to a specific resource ('Cyclesite listing') with defined categories (excellent/good/fair/weak) and additional outputs (wins/flags). It distinguishes itself from listing details or safety tools by focusing on trustworthiness grading.

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?

Provides clear usage context: helps buyers assess trustworthiness and sellers self-audit, with an example query. However, it does not explicitly mention alternatives or exclusions, though the note about returning only categorical judgment implies not using it for underlying scores.

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, openWorldHint, idempotentHint. The description adds beyond that by disclosing that stock counts are returned as bands (none / 1-5 / 6-25 / 26-100 / 100+) due to Cyclesite not exposing precise inventory, and that results are ordered by stock level. This is valuable behavioral context not present in 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?

The description is three compact sentences that front-load the core purpose, then provide usage guidance, and finally disclose the stock-band limitation. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the existence of an output schema, and the annotations, the description covers purpose, usage, and a key behavioral limitation. It is complete for an agent to select and invoke the tool 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?

The input schema already fully documents q, limit, and offset with descriptions (100% coverage), so the baseline is 3. The description adds general context about pagination and ordering but doesn't add new parameter-specific semantics 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 clearly states the tool lists a paginated catalogue of UK bike brands from Cyclesite, ordered by stock level, and distinguishes it from sibling tools like list_models_for_brand by focusing on brands. It also gives concrete use cases (validate a brand name, surface options, paginate). This is a specific verb+resource+scope statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use it: to validate a brand name, surface options to a user, or paginate the catalogue. It doesn't name alternatives or exclusions, but the context is clear enough for an agent to select it over related tools like list_models_for_brand.

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 description adds pagination behavior ('paginated') and the specific returned fields, which are not included in the annotations. It does not contradict the readOnlyHint, openWorldHint, or idempotentHint, and the example illustrates a typical workflow.

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 only three sentences: one for resource/pagination, one for returned fields, and one for a concrete example. Every sentence delivers unique value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a rich output schema and strong annotations, the description covers all key aspects needed for invocation: purpose, return fields, pagination, and a worked example. The only omission is explicit exclusions, but those are secondary given the tool's simplicity.

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 schema already explains brandSlug, limit, and offset, covering 75% of parameters. The description adds context for the category parameter via example ('road') and ties brandSlug to list_brands output, but this is modest beyond schema coverage.

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 ('Models for a brand') and the return payload ('model names, year ranges, in-stock flag'). The example workflow ('list_brands → list_models_for_brand') further distinguishes it from sibling tools like list_brands and get_model_info.

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 shows a specific use case ('what Trek road bikes are available?') and the intended sequence with list_brands, which provides a solid when-to-use context. However, it does not explicitly mention when not to use the tool or list alternative tools to avoid.

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 (readOnlyHint, openWorldHint, idempotentHint), the description discloses the OAuth scope requirement (`listings:read`) and clarifies the user-specific data scope. It does not detail pagination or return format, but with strong annotations this is adequate.

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 concise sentences with a front-loaded purpose, scoping, and requirement. The example is a single clause. No 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?

Given the simple two-param schema, strong annotations, and presence of output schema, the description is mostly complete. It covers purpose, auth, and scope. Minor gap: does not mention the 'all' status option, which could be slightly ambiguous.

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% (limit has minimal '1-20.' description, status has no description beyond enum), and the tool description adds no parameter details. It mentions statuses 'draft/active/sold' but omits 'all', which could confuse. No explanation of limit semantics or default behavior.

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 ('Show') and resource ('authenticated user's Cyclesite listings') with explicit statuses (draft/active/sold). It clearly distinguishes from sibling tools like get_my_enquiries or get_my_messages, and the example 'how are my listings doing?' reinforces the intended use.

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?

Provides a clear example ('how are my listings doing?') indicating when to use, and scopes the tool to authenticated user's listings. It does not explicitly contrast with alternatives, but the context is sufficient for an agent to select it over listing-query tools like get_recent_listings or search.

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 description adds substantial behavior beyond the annotations: the enquiry is saved to the buyer's inbox, the seller is notified, there is a per-buyer-per-listing daily cap of 2, and the required OAuth scope is named. It also clarifies the scope-name ambiguity with seller-side replies. These are exactly the side-effect and context details an agent 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?

The description is compact and front-loaded: action first, then key side effects, capabilit constraints, and a useful example. Every sentence carries distinct information and nothing feels redundant or padded.

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 tool with an output schema and annotations, the description is complete: it states the action, destination, notification side effect, spam limitation, authorization requirement, and where to read the reply. No critical operational detail 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?

The schema already covers both parameters with clear descriptions, so the baseline is 3. The description adds value with a concrete natural-language example that shows how a buyer request maps to listingId and message content, including negotiation details like price and collection location. This extra example meaningfully helps an agent construct the call.

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 on the buyer's behalf.' It clearly distinguishes this buyer-initiated action from sibling tools like respond_to_enquiry and get_my_messages, and the example reinforces the intended use.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool and even routes follow-up behavior: 'Read the seller's reply with get_my_messages.' It also notes the OAuth scope prerequisite and the daily cap. It could more explicitly contrast with respond_to_enquiry, but the sibling differentiation is implied well enough.

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 indicate the tool is destructive, non-read-only, idempotent, and open-world. The description adds useful context beyond that by specifying the OAuth scope `listings:manage` and by showing a natural-language invocation example. No contradiction with the annotations exists.

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 dense sentences with no filler. The core action is front-loaded, followed by the auth requirement and a useful example. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and annotations, the description covers the essential behavioral context: what the tool does, required permission, and how natural-language input may look. It could be slightly stronger by explicitly distinguishing this from related tools, but the combination of description, schema, and annotations is sufficient for an agent to invoke 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 coverage is 75%, so most parameters are already documented in the schema. The description adds value by paraphrasing the optional fields ('final sale price, where it sold and the date it sold') and providing a natural-language example that maps to salePriceGbp, saleVenue, and soldOn. However, it does not clarify the listingId parameter, which is also undocumented in 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 uses a specific verb and resource: 'Mark a Cyclesite listing as sold', with optional details around price, venue, and date. This clearly distinguishes it from sibling tools like reserve_listing, publish_listing, or report_stolen. The concrete example further reinforces the intended action.

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 usage context is implied: use this when a listing has actually sold and needs to be marked as such. It states a required OAuth scope, which is a precondition, but it does not explicitly say when not to use it or mention alternatives such as reserve_listing for holds or report_stolen for theft.

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 the multi-step statefulness, photo upload requirement, Stripe payment path, idempotent retry behavior, OAuth scope, and 24-hour undo email. This significantly exceeds what readOnlyHint/openWorldHint/idempotentHint/destructiveHint already communicate.

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 dense but every sentence earns its place: purpose, step flow, idempotency, auth, and a concrete example. The most important information is front-loaded and the example flow is illustrative without being 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?

Given the tool's complexity — 24 parameters, multi-step behavior, output schema, and many siblings — the description is remarkably complete. It covers the full user journey, auth requirement, retry semantics, payment branching, and post-publish undo, so an agent can invoke it correctly without external help.

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 description clarifies draftId's lifecycle (omit on first call, reuse until step:'live') and the photo-count prerequisite, which adds meaning beyond the schema. However, with only 54% schema coverage and 24 parameters, it does not compensate for the many undocumented fields such as year, brand, model, priceGbp, or groupset.

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: 'Publish a Cyclesite listing on the user's behalf.' It clearly conveys a multi-step publish operation and differentiates itself from read-only siblings through its live/payment flow, though it never explicitly names a sibling like draft_listing for contrast.

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 concrete when-to-use context via the example flow ('user says sell my Trek Domane → call publish_listing') and states the OAuth prerequisite. It does not explicitly say when not to use it or mention alternatives, but the sequential call guidance ('keep calling with the same draftId until step:"live"') is useful.

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 (readOnlyHint, openWorldHint, idempotentHint), the description adds behavioral insights: 'Prefers higher-engagement listings' discloses a ranking preference, and 'Returns up to 5 picks with a one-line rationale each' explains the output structure. This extra context helps the agent understand what to expect beyond the safety guarantees already provided.

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—two sentences plus a list of examples—yet packs essential information. The primary purpose is front-loaded, examples are illustrative without being verbose, and there is no redundancy with 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?

For a recommendation tool with a clear schema and annotations, this description is complete. It covers the source ('live UK inventory'), the selection criteria ('budget and intent', 'higher-engagement listings'), the output format (up to 5 picks with rationale), and gives practical examples. The presence of an output schema means return values need not be detailed further.

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 80%, so the baseline is 3, but the description adds semantic value by showing how budget, intent, and category combine in examples. For instance, 'a road bike for £1,500 for weekend rides' implicitly maps to budgetGbp=1500, category=road, and useCase=weekend rides, which clarifies the intended usage of the free-text 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 opens with 'Curated picks from Cyclesite's live UK inventory for a budget and intent,' clearly stating the action (curating picks) and resource (bikes from live inventory). It distinguishes itself from sibling search tools by emphasizing 'curated picks' and 'prefers higher-engagement listings,' which signals a recommendation engine rather than raw 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?

The description provides three concrete example queries ('a road bike for £1,500 for weekend rides', 'best e-MTB I can buy under £3,000', 'commuter bike in London under £400'), which clearly illustrate the intended usage context and parameter combinations. However, it does not explicitly state when not to use this tool or mention alternative sibling tools, 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 declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering the safety profile. The description adds useful behavioral context: it returns a checklist and URL, focuses on UK bikes, and is guidance rather than an actual report submission. No contradiction with 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?

The description is only two sentences, front-loads the core purpose, and includes a useful example. Every sentence adds value and there is no filler or 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?

For a low-complexity, read-only tool with no required parameters and an output schema, the description covers the purpose, output, scope, and a realistic invocation scenario. The main weakness is the unexplained optional parameters, but that gap is already reflected in the parameter-semantics score.

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 does not explain the roles of brand, model, or serial. Those parameters are left as bare strings with no guidance on whether they tailor the checklist or are only optional context. The description fails to compensate for the schema's lack of semantic 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?

The description clearly states the tool's purpose: providing step-by-step guidance for reporting a stolen UK bike, and it names the concrete output (a 5-step checklist plus the official Cyclesite report URL). This distinguishes it from related sibling tools like check_stolen in practice, though it does not explicitly name an alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear invocation scenario via the example query and lists the relevant report areas (police, insurance, listing alerts). It lacks explicit when-not-to-use or alternative tool guidance, but the context is unmistakable for a bike-theft reporting scenario.

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 description discloses several non-obvious behaviors: the hold is free and advisory, the seller is not obligated to honor it, OAuth scope is required, and deposit-backed holds are not yet available. This adds significant context beyond the annotations, which only indicate non-read-only, open-world, idempotent, and non-destructive hints.

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 primary purpose and includes a useful example. The marketing sentence ('The first UK marketplace...') adds little functional value, but overall the description remains concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides essential operational context: 24-hour duration, free/advisory nature, OAuth requirement, and deposit limitation. Since an output schema exists, return values need not be described. No critical gaps remain for a simple hold mutation.

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 schema description coverage at 50%, the description compensates by clearly explaining that depositGbp should be omitted because deposits are unavailable. It does not elaborate on listingId, but the parameter name is self-explanatory and the example implicitly illustrates its usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's specific action ('Hold a Cyclesite listing') and its purpose ('so other buyers can't claim it while the user decides'), distinguishing it from siblings like publish_listing or mark_as_sold. The inclusion of a time frame (24 hours) makes the scope precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: when a user wants to temporarily secure a listing before deciding. It explicitly warns against offering deposits today and suggests messaging the seller to confirm, which is a practical after-step. However, it does not explicitly contrast with alternatives (e.g., make_enquiry) or name higher-level alternatives.

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 the operation as non-read-only and destructive. The description adds the OAuth requirement and a concrete example, but does not explain side effects or irreversibility beyond what annotations imply.

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 concise sentences: purpose, auth requirement, and example. Information is front-loaded with 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?

With only two parameters, an output schema, and annotations covering the safety profile, the description provides enough context to call the tool correctly. It could mention destructive effects explicitly, but this is largely covered by annotations.

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 schema describes 'answer' but leaves 'enquiryId' undocumented. The description's example clarifies the intended answer style, but it adds little formal meaning beyond the schema; enquiryId is inferable from the name.

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: 'Reply to a buyer enquiry on the authenticated user's listing.' This clearly distinguishes it from siblings such as make_enquiry or 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?

Provides clear context: this tool is for responding to an existing buyer enquiry, and it names the required OAuth scope. It does not explicitly list when not to use it or name alternative tools, so it stops 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?

The description discloses the OAuth scope nuance ('listings:read' but technically a write), explains the creation of a SavedSearch row, and notes the 50-alert cap. It adds substantial context beyond the annotations, including the proactive notification behavior and the distinction between read and write semantics.

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 three sentences long, front-loaded with the main purpose, and every sentence adds value: purpose, auth nuance, examples, and cap constraint. 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?

Given the output schema exists and the description covers purpose, auth, examples, and constraints, it is highly complete. However, it does not address behavior near the cap (e.g., error handling) or whether multiple identical alerts are allowed, which are minor 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 only 33%, but the description compensates with examples that map to parameters (brand, model, city, maxPrice, category). It does not exhaustively explain every parameter but provides enough grounding for filter construction.

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 ('Subscribe') and a clear resource ('alerts for new Cyclesite listings matching a filter'), with concrete user-facing examples that illustrate the behavior. It clearly distinguishes from sibling search tools by emphasizing proactive notification rather than immediate results.

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 examples strongly imply when to use this tool (e.g., when a user asks to be notified about future listings), but it does not explicitly state 'use this instead of search' or provide exclusion criteria. The context is clear enough for an agent to infer the appropriate scenario.

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 the tool read-only, idempotent, and open-world. The description adds meaningful context beyond those: it states the search matches title/brand/model, returns the canonical OpenAI shape with only id/title/url, and directs the agent to call fetch() for full documents. This helps set expectations about the lightweight nature of the results and the follow-up workflow, though it does not cover rate limits or pagination.

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 only three sentences, front-loaded with the tool's compatibility purpose, then the core search behavior, then the output format and next step. Every sentence contributes value, and there is no redundant or filler wording. It is concise yet information-dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter) and the presence of annotations and output schema, the description is fully complete. It clarifies the scope (active UK used-bike listings), search fields, output shape, and the follow-up call to fetch. No critical information is missing for an agent to effectively select and invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema describes 'query' only as a free-text string. The description adds crucial semantics by explaining that the query matches title, brand, and model fields, and that it returns results in a specific shape. This gives the agent a better understanding of how the query is interpreted, going beyond the bare schema 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 specifies exactly what the tool does: search Cyclesite's active UK used-bike listings by free-text query. It names the resource (active UK used-bike listings), the action (search), and the searchable fields (title, brand, model). It also distinguishes itself from siblings by highlighting 'OpenAI deep-research / company-knowledge compatibility' and the canonical OpenAI output shape, clearly differentiating it from alternative search tools like 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 description gives clear context that this tool is intended for OpenAI deep-research / company-knowledge use cases, and it explicitly tells the agent to use the returned id to call fetch() for the full document. This is actionable guidance, though it does not explicitly mention when not to use other search siblings or provide exclusions. Overall, the intended usage is clear.

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, open-world, and idempotent behavior. The description adds useful behavioral detail: it returns up to 5 active listings, includes specs and URLs, and uses live continuously-refreshed data. No contradiction with 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?

The description is compact and front-loaded: the core purpose appears in the first sentence, followed by output scope, data freshness, and examples. Every sentence contributes practical value with no 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?

With a full schema, an output schema, and annotations covering safety semantics, the description supplies the remaining context: platform, market scope, result limit, freshness, and example query phrasings. An agent has enough to decide when and how to call this 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?

All parameters are fully described in the input schema, so the description does not need to repeat them. It does map filters ('brand, category, city, price range, and condition') to the parameter set and gives useful natural-language examples, but it adds little 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 names a specific verb ('Search'), a precise resource ('live UK used-bike listings on Cyclesite'), and a clear scope (UK used-bike marketplace). It also distinguishes itself from generic siblings like 'search' by emphasizing live listings and the Cyclesite platform.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use it: when the user wants live UK used-bike listings from Cyclesite. Example queries reinforce the intended usage patterns. It does not explicitly name alternatives or exclusions, so it stops 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 declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: radius cap (50 miles), max results (10), distance ordering, live data, and the prerequisite to geocode first. This goes beyond annotations and helps the agent set 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 two sentences plus an example, with no wasted words. It front-loads the core purpose, then adds constraints, and finishes with a practical example. Every sentence contributes to understanding the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, 2 required) and the presence of an output schema, the description covers the essential behavior, constraints, and usage example. It does not mention error handling or edge cases, but for a read-only tool with strong annotations, this is sufficient.

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%, with lat, lng, limit, and radiusMiles described. The description mentions the radius cap and result limit but does not add new meaning to parameters beyond what the schema provides. Since coverage is moderate but not low, the description is not required to compensate heavily; it adds minimal extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Find', the resource 'Cyclesite listings', and the specific scope 'within a radius of a UK location (lat/lng)'. It also adds distinguishing constraints like radius cap and return limit, making it distinct from sibling search tools. The example further clarifies the intended use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a concrete example ('used bikes within 25 miles of LE10 0AA') and instructs to geocode the postcode first, implying when this tool is appropriate. However, it does not explicitly mention alternatives or when not to use it, leaving some inference required.

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, openWorld, and idempotent, so the bar for extra disclosure is lower. The description adds valuable behavioral context: the response contains ask/floor/ceiling, the `basis` field always names the derivation source, and year anchoring falls back to the all-years median when the curve doesn't cover that year. This goes well 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?

Three purposeful sentences plus a compact example. The purpose and scope are front-loaded, the get_valuation distinction is one clause, and the example demonstrates realistic usage without padding.

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-value documentation is unnecessary. The description covers the target user, data source, market scope, year-optional behavior, fallback behavior, and output fields (ask/floor/ceiling/basis). Nothing essential for an agent to invoke this correctly 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 only 25%, so the description must compensate. It does meaningfully explain the `year` parameter's optionality and anchoring behavior, and the example demonstrates condition usage. Brand and model remain lightly described, but their semantics are fairly self-evident and the schema marks them required.

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?

Description states a specific verb and resource: suggest ask/floor/ceiling for a seller's bike on the UK market. It explicitly differentiates from get_valuation by calling out the same data but seller-guidance framing, which clearly separates it from the nearest sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description opens with 'For a seller about to list', establishing the target scenario, and explicitly contrasts with get_valuation. It also gives concrete conditional guidance: pass `year` when the seller names one, supported by a worked example.

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