cyclesite-mcp-server

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds key behavioral traits: per-serial rate limiting (3/hour) to prevent enumeration, live data cross-referencing multiple registries, and aggregation of UK stolen-bike databases. This significantly enhances transparency 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 front-loaded with the purpose and includes an example, rate limit, and live data context. It is compact but contains a minor fluff phrase ('the unique data we own') that doesn't add functional value. Overall, each sentence earns its place except that one, so 4 is fair.

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, strong annotations), the description is complete: it covers purpose, usage example, rate limiter, live data behavior, and data scope. There are no significant gaps 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 100% and the single 'serial' parameter is well described ('Frame/serial number (4-50 chars)'). The description adds an example serial format ('WTU123456') but no additional semantic meaning beyond what the schema already provides. Thus 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 clearly states the tool's function: 'Check if a UK bicycle is reported stolen by serial number.' It uses a specific verb ('check') and resource ('UK bicycle'), and the scope (by serial number) distinguishes it from siblings like report_stolen or search 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 description provides clear context: use when you need to verify a UK bike's stolen status by serial number, with an explicit example query. It also notes a rate limit. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., report_stolen for reporting), so exclusions are implied rather than stated.

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

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

Annotations already declare 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 declare readOnlyHint=true and openWorldHint=true, so the description adds value by explicitly stating 'Does NOT publish' and clarifying the non-destructive drafting behavior. It also provides an example that illustrates the expected input pattern. This goes beyond 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?

The description is three sentences long and each sentence earns its place: the first defines the tool's function, the second draws the critical boundary with publish_listing, and the third provides a concrete usage example. 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?

Although the tool has 9 parameters, the description covers the core purpose, the non-publication boundary, and gives a realistic example. The output schema is available to explain return values, so the description doesn't need to. The mention of OAuth for publish_listing also provides useful context. Slightly more detail on how to structure inputs for the optional parameters would push this to 5, but it is complete enough for an agent to use 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?

Schema description coverage is only 11% (only knownIssues has a description), so the description must compensate. It does so implicitly via the example '2021 Specialized Allez, very good condition, in Bristol,' which maps to year, brand, model, condition, and city. However, it does not explain other parameters like willShip, groupset, or frameSize, though their names are somewhat self-explanatory. This is adequate but not comprehensive.

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 the tool's specific function: 'turn a seller's raw facts into a polished Cyclesite listing draft' with concrete outputs like title, description, suggested price, and photo plan. It clearly distinguishes itself from sibling publish_listing, positioning this tool as a drafting helper rather than a publication tool.

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 when-to-use guidance: 'Sell-side helper' and 'Useful for previewing what a listing would look like.' It also names the alternative: 'for actual publication use publish_listing (requires OAuth),' making the decision between these siblings unambiguous.

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, openWorldHint, and idempotentHint. The description adds behavioral specifics beyond these: returns up to 5 results, filters by active status, and describes the similarity algorithm. This enhances understanding 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?

Two sentences: the first states core behavior with criteria, the second gives usage trigger and an example. No fluff, front-loaded with the most critical information.

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

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

With one well-documented parameter and an output schema present, the description fully covers what the tool does, when to use it, and what it returns. It also includes an example of user intent, making it complete for an agent to select and invoke 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 schema has full coverage (100%) for the single 'slug' parameter with a clear description. The tool description repeats this ('Given a Cyclesite listing slug') but doesn't add syntax or format details, so it adds minimal value 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's function: 'return up to 5 similar active listings' given a listing slug. It specifies the exact similarity criteria (same category, ±25% price, brand/frame size weighting), which distinguishes it from sibling tools like search_bikes 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?

Provides explicit when-to-use guidance: 'Use when the user is interested in one bike and wants alternatives' with a concrete example. While it doesn't mention exclusions or alternative tools, the stated use case is clear and contextually distinct.

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?

Beyond the readOnly and idempotent hints, the description reveals specific behavioral traits: a 15-minute refresh cycle, a maximum of 10 results, and filtering options. It also discloses the data scope ('active UK listings') and liveness, giving agents a clear mental model of what to expect 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 concise and front-loaded with the core purpose, followed by usage context, filter notes, and a liveness statement. Every sentence contributes meaningful information, with no wasted words or redundant elaboration.

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 tool (3 optional params, output schema exists), the description covers all key aspects: purpose, when to use, filters, freshness, and scope. There is no need to explain return values since an output schema is present, and the description is complete for an agent to decide correct 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 description adds minimal semantic value for parameters: it notes 'Optional category + maxPrice filters,' which clarifies their role but does not detail category values or interactions. Schema coverage is 67%, with category lacking a description; the enum provides the list, and limit and maxPrice have schema descriptions. The description does not fully compensate for category's missing description but is adequate.

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 returns the freshest active UK listings, with a concrete scope (up to 10, refreshed every 15 minutes). It also distinguishes itself from siblings by explicitly stating it is not for specific filters, making the purpose and boundaries 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?

It provides explicit when-to-use guidance with example queries ('what's new today?', 'any new road bikes this week?') and directly contrasts with 'specific filter' use cases, implying alternatives like search. This is strong contextual guidance beyond a generic 'use for recent listings.'

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

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

The description discloses the data source ('Cyclesite's real UK listings') and fallback behavior ('Falls back to industry-standard charts when the dataset is thin'). These add context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), which already signal a safe, read-only operation. 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 two sentences plus an example. It front-loads the purpose, then adds sourcing and fallback context, and ends with a concrete example. Every sentence carries value, with no redundant or vague wording.

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

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

Given the tool is read-only, has an output schema, and simple parameters, the description covers the essential aspects: what it does, how it sources data, fallback behavior, and a usage example. It does not need to explain return values because an output schema exists. Complete for its complexity.

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 heightCm fully with a range, but category only has an enum with no description. The description adds the phrase 'bike category' and gives a 'road-bike' example, providing slight clarification. However, schema coverage is 50% and the description does not fully elaborate category values beyond the example, so it only partially compensates.

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: 'Frame-size recommendation for a rider's height and bike category.' It uses a specific verb ('recommendation') and resource ('frame-size'), and the example 'I'm 178cm — what road-bike size do I need?' confirms the exact use case. It also distinguishes itself from siblings like get_buying_guide by focusing on frame sizing rather than a general buying guide.

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 example of when to use the tool, implying the input format and context. It does not explicitly mention alternatives or when not to use it, but the example and focus on frame-size make the usage context clear. Lacks an explicit exclusion or alternative comparison, so not a 5.

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

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

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?

The description adds significant context beyond the annotations (readOnly, openWorld, idempotent): it discloses that values are based on last-advertised asking prices (not confirmed sale prices), data is refreshed nightly, and it returns a measured curve and confidence level. This is valuable for setting expectations about data quality and 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 concise and well-structured: it front-loads the purpose, lists return values, explains the data source and caveats, and ends with a concrete example. Every sentence serves a purpose 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 an output schema present, the description doesn't need to explain return structures. It provides a clear functional overview, data source, caveats, and an example, making the tool easy to select. The only gap is the lack of explicit parameter documentation, keeping it from a perfect 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?

With 0% schema description coverage, the description was expected to compensate, but it provides no explicit guidance on the 'brand' and 'model' parameters. While the example shows a specific brand and model, it does not clarify required formats, case sensitivity, or other constraints, leaving the agent to infer parameter semantics from the example alone.

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 the current worth of a used UK bike. It lists specific outputs (median, range, price-by-model-year curve, confidence level, comparable listings) and positions it as 'Cyclesite's flagship tool', distinguishing it from siblings like get_price_trends or get_depreciation.

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 through 'right now' and provides an explicit example query ('what's a 2022 Trek Domane SL 6 worth?'), indicating when to use it for current valuation. However, it does not explicitly contrast with alternatives or mention scenarios where other tools would be more appropriate, such as historical trends or depreciation.

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?

Beyond annotations, the description discloses that the enquiry is saved to the buyer's inbox, the seller is notified, there is a per-buyer-per-listing daily cap, and the required OAuth scope is shared with seller-side replies. This is rich, non-obvious behavioral context that helps the agent anticipate side effects and auth nuances.

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 concise sentences: purpose, behavior/limit, and follow-up/auth. It includes a practical example without rambling. Every sentence earns its place, and the most crucial information is front-loaded.

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 action with an output schema, the description covers the purpose, effects, rate limit, auth scope, follow-up tool, and an example. No critical gaps remain 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 schema already covers both parameters at 100% coverage, providing a baseline of 3. The description adds value by cross-referencing listingId to search_bikes/get_listing_detail and giving a concrete natural-language example ('message the seller of that Trek...'), which helps the agent map user intent to the 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 specific verb+resource: 'Send an enquiry to a Cyclesite seller on the buyer's behalf.' This clearly distinguishes it from sibling tools like get_my_enquiries (viewing) and respond_to_enquiry (seller-side replies), and the action is 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?

It provides practical when-to-use context: it's the buyer-facing send action, notes the daily cap to discourage overuse, and points to get_my_messages for reading the reply. However, it doesn't explicitly state exclusions or alternatives like 'use respond_to_enquiry if you are the seller,' so it misses the top tier.

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 authorization requirement and the optional sale price behavior, adding context beyond the annotations. Annotations already indicate the write, idempotent, and non-destructive nature, and no contradiction is present. It could mention side effects, but the provided details are sufficient.

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: the first front-loads the core action and scope requirement, the second provides an illustrative example. Every word adds value, and there is 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 only two simple parameters, an output schema, and clear annotations, the description covers purpose, usage, authorization, and example. It does not need to detail return values because the output schema exists. It is complete for this tool's complexity.

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 0% description coverage, so the description must compensate. It does so by mapping 'final sale price' to salePriceGbp and giving an example in GBP. listingId is self-evident from the context. This adds enough meaning for both parameters.

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

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

The description clearly states the action and resource: 'Mark a Cyclesite listing as sold'. It distinguishes this tool from sibling tools like publish_listing or reserve_listing by specifying 'as sold' and the optional final sale price. The example further clarifies 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 explicitly mentions the required OAuth scope (`listings:manage`) and provides a concrete usage example, giving clear context for when to use it. It does not explicitly mention when not to use it or alternatives, but the unique action makes the usage 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?

Adds substantial behavior beyond annotations: phone-friendly photo upload URL, 3+ photo requirement, fee amount with Stripe Checkout, OAuth scope, idempotency retry semantics, and a 24h undo email. Annotations only indicate idempotent/openWorld/mutating; this description enriches all of that.

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 yet logically structured: purpose, step-by-step flow, idempotency, OAuth, example. Every sentence adds operational detail needed to execute correctly; there is no fluff.

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 high complexity (multi-step, payment, OAuth, state transitions), the description covers return states ('step:live' / 'step:payment_required'), prerequisites, and the full example flow. With an output schema present, return field detail is not required here.

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

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

Schema coverage is only 33%, and the description does not compensate for the many undocumented parameters (brand, model, priceGbp, condition, frameSize, etc.). It adds context for draftId continuation and price/fee semantics, but leaves most parameter meaning unexplained.

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'), and the multi-step flow clearly distinguishes it from sibling tools like draft_listing. It states exactly what action is performed.

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 workflow: first call without draftId, then keep calling with the same draftId until step:'live'. Includes an example flow. It does not explicitly mention alternatives or when not to use this tool, but the draftId mechanism implies a prior draft step.

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 mark readOnly/openWorld/idempotent; the description adds that it returns a 5-step checklist and official Cyclesite URL, and that it's guidance rather than an actual report. No contradictions.

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 verb/resource, includes output structure and a concrete example. 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?

Given the tool's low complexity and the available annotations/output schema, the description covers purpose, output, and a triggering example. The only gap is parameter semantics, but optional params and a safe, read-only tool make this less 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 coverage is 0% and the description doesn't explain how brand, model, or serial affect the output or whether they are needed. The agent gets no guidance on populating these optional parameters.

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

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

The description clearly states the tool provides step-by-step guidance for reporting a stolen UK bike, covering police, insurance, and listing alerts, and specifies the returned checklist and URL. This distinguishes it from siblings like check_stolen by focusing on the reporting workflow.

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

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

The example query ('my bike was just stolen, what do I do?') gives clear context for when to use it. It doesn't explicitly name alternatives or exclusions, but the use case is unambiguous.

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?

The description discloses the required OAuth scope `enquiries:respond` and the behavioral context of replying on the authenticated user's behalf. Annotations already mark it as a mutation (readOnlyHint=false) and not destructive, so the description adds auth and usage context without contradiction.

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

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

The description is two sentences plus a short example. It is front-loaded with the action, then states the auth requirement, and ends with a concrete usage scenario. No redundant words are present.

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 two-parameter mutation tool with an output schema, the description covers purpose, auth, and example usage. It does not mention error conditions or side effects, but these are not critical given the annotations and output schema.

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` with a length constraint, but `enquiryId` has no description. The description's example ('say it's still available, collection only') adds semantic meaning to `answer` but does not elaborate on `enquiryId`. With 50% schema coverage, the description only partially compensates.

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 the specific verb 'reply' and clearly defines the resource as 'a buyer enquiry on the authenticated user's listing'. The example further clarifies the intended use, distinguishing it from sibling tools like 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?

The description clearly implies when to use the tool (when replying to a buyer's enquiry on one's own listing) and provides a concrete example. However, it does not explicitly mention alternatives or when not to use, 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?

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 provide readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral details beyond these: 'Live data — refreshed continuously' and 'Returns up to 5 active listings', which set expectations about freshness and result limits. 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 four sentences, front-loaded with the core action, and every sentence earns its place: function, filters, result characteristics, and illustrative examples. There is no redundancy or fluff.

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 search tool with 6 parameters and output schema, the description covers the marketplace, live data, result limit, and filter capabilities, plus practical examples. It does not explain return structure, but an output schema exists, so that is not required. It is sufficiently complete for agent invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lists filter dimensions (brand, category, city, price range, condition) that map directly to parameters, and the example queries like 'under £2,000' slightly illustrate semantics, but it adds little meaning beyond the already descriptive 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 opens with 'Search live UK used-bike listings on Cyclesite', naming the specific verb, resource, and scope. It distinguishes itself from siblings like search_by_location by focusing on the Cyclesite marketplace and used bikes, while also listing concrete filter dimensions.

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 context is clear: this is for searching used-bike listings on Cyclesite with given filters, supported by example queries. However, it does not explicitly mention when to use an alternative tool (e.g., 'use search_by_location for location-only'), so it lacks formal exclusions but has strong implied usage.

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?

Discloses additional behaviors beyond annotations: radius capped at 50 miles, returns up to 10 listings ordered by distance, and live marketplace data. These complement the readOnly/openWorld/idempotent hints without 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 concise sentences plus an example; front-loaded with purpose, then constraints, then usage. 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 output schema and annotations, the description covers key behaviors and usage. It does not elaborate on all optional filters but is adequate for a location-based search 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 covers 67% of parameters. Description adds context for radius limit and limit default, and gives an example. However, it does not explain the undocumented category and maxPrice parameters, leaving a 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 the tool finds Cyclesite listings within a radius of a UK location, with a specific verb, resource, and scope. However, it does not explicitly differentiate from sibling search tools like search 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?

Provides clear usage context: geocode postcode first, radius cap, max results. But it does not explicitly state when to use it over alternatives or mention exclusions.

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 as read-only and idempotent, so the bar is lower. The description adds useful behavioral context: UK market data source and that it's seller guidance, which 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?

The description is two concise sentences plus a clear example. Every element earns its place: the core purpose, the data source context, and an illustrative query. No fluff.

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 tool has an output schema, so return values are covered. The description provides enough context for when to use it (seller listing), the data basis (same as get_valuation), and an example. For a 3-parameter tool, this is complete.

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

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

The schema has 0% description coverage, so the description must compensate. It mentions brand+model+condition and provides an example with 'good' condition, but it doesn't explain the enum values or the units/meaning of the returned price ranges. This is adequate but not fully compensating 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 the tool provides suggested ask, floor, and ceiling prices for sellers, using brand+model+condition on the UK market. It also distinguishes itself from get_valuation by noting it's the same data but framed as seller guidance.

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 sets explicit context ('For a seller about to list') and contrasts with get_valuation, implying when to use this tool versus that alternative. However, it doesn't explicitly mention exclusions or other potential alternatives like get_price_trends.

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