cyclesite-mcp-server

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds valuable behavioral context: live data cross-referencing multiple registries and per-serial rate limiting, which go 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 concise (3 sentences), front-loaded with the main purpose, and every sentence adds value. No unnecessary words.

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, presence of output schema, and rich annotations, the description is complete. It covers data source, rate limit, example, and operational details, requiring no additional information.

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 description does not add significant new meaning. It repeats the serial number requirement and gives an example, but the schema already describes the parameter adequately. Baseline score 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 checks if a UK bicycle is reported stolen by serial number. It specifies the verb 'check' and the resource 'stolen status,' and distinguishes from siblings like 'report_stolen' which would be for reporting rather than checking.

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 rate limit (3/hour per serial) and an example query, indicating when to use the tool. While it does not mention when not to use or direct alternatives, the context of sibling tools makes 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?

Annotations already indicate read-only, idempotent, and open-world. Description adds that it internally calls get_spec_sheet and get_valuation, returning combined results. This provides useful behavioral context beyond 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 concise sentences plus an example. No redundant information. Every sentence adds 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?

Description covers input structure, limit of 3 bikes, and combined output purpose. Output schema exists, so no need to detail return fields. Slight gap: no mention of error handling or behavior when bikes are not found, but overall adequate for a composite read 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 has 0% description coverage, but description explains the 'bikes' parameter: up to 3 bikes, each identified by brand, model, and optional year. Provides an example that clarifies usage. Adds meaning beyond the bare schema structure.

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 performs side-by-side comparison of up to 3 bikes, using brand+model+year. Includes an example, making purpose explicit. Differentiates from sibling tools like get_spec_sheet and get_valuation by noting it reuses them server-side.

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?

Description explains when to use (comparing bikes with spec sheets and valuations) and gives an example. Implicitly informs that individual tools exist for separate needs, but does not explicitly state when not to use this tool.

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

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

The description clarifies that the tool only creates a draft and does not publish, which aligns with the readOnlyHint annotation. The openWorldHint is noted from annotations but not mentioned in the description; however, the draft nature implies potential hallucination. 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?

The description is two sentences plus an example, with no unnecessary words. It efficiently communicates purpose, usage distinction, and provides a concrete usage scenario.

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 9 parameters and the presence of output schema and annotations, the description covers high-level purpose and sibling distinction but lacks parameter guidance and explicit mention of open-world behavior. It is adequate but not comprehensive.

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 only 11% schema coverage (only knownIssues has a description), the description should compensate but does not. It only mentions 'brand' and 'model' in the example, leaving 7 parameters with no added meaning. The example gives context but insufficient for all 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's function: 'turn a seller's raw facts into a polished Cyclesite listing draft (title, description, suggested price, photo plan).' It uses specific verbs and resources, and explicitly distinguishes it from publish_listing, a sibling 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 contrasts the tool with publish_listing, stating it does NOT publish and is useful for previewing. An example is provided. It could explicitly state when not to use (e.g., for final publication) but the sibling distinction serves that purpose.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the description adds value by specifying the return fields and that text is a plain-prose summary. 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?

Two sentences, front-loaded with key purpose, no fluff, every sentence adds 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?

For a simple tool with one parameter and output schema mentioned, the description covers purpose, return structure, and use case. No 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?

Only one parameter 'id' with schema description 'Document id from search results.' The description does not add additional meaning beyond what the schema provides; schema coverage is 100% so baseline is 3.

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 fetches the full document for a Cyclesite listing id, with specific return fields and a note about plain-prose summary suitable for deep-research. It differentiates from sibling search tools by indicating it is used after search 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 description indicates usage after the search tool ('returned by the search tool'), but does not explicitly mention when not to use or alternative 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?

The description adds behavioral details beyond the annotations (readOnlyHint, openWorldHint, idempotentHint): it returns up to 5 results, only active listings, and applies specific filtering criteria. This provides useful constraints that are not captured by annotations alone.

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 (three sentences) and well-structured. It front-loads the core function, then provides usage guidance, and ends with an example. No redundant 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?

Given the simple parameter set, the presence of annotations, and an output schema, the description is complete. It covers what the tool does, when to use it, and the outcomes. No critical 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?

Schema coverage is 100% with one parameter already described. The description adds minimal extra meaning beyond 'slug' by contextualizing it as a 'Cyclesite listing slug'. This meets the baseline for high coverage but does not significantly enhance understanding.

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: given a listing slug, return similar active listings. It specifies the algorithm (same category, ±25% price, weighted by brand/frame size) and the result count (up to 5). This distinguishes it from sibling tools like search or recommend_bike_for_budget.

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 the tool: 'Use when the user is interested in one bike and wants alternatives.' It also provides an example query. However, it does not mention when not to use it or point to alternative tools, which would elevate it to 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?

Adds details beyond annotations: returns up to 3 guides, lists returned fields, mentions source (24+ articles by cycling-journalism authors). 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?

Two sentences with example, front-loaded key purpose. Every word is useful.

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 output schema exists and description covers return fields, the tool is fully described for agent use.

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%. Description adds example queries and clarifies limit range (1-5, default 3) beyond 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?

Description clearly states the tool searches buying guides with specific fields returned. It distinguishes from sibling tools like search_bikes by indicating it's for educational queries.

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?

Explicitly says 'Use for educational queries that don't need live inventory' and provides example queries. Does not explicitly state when not to use or name alternatives, but context 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?

Discloses data source (Cyclesite's UK used-price data), metric (% retained vs new RRP), and default behavior (top N). Annotations already indicate read-only and idempotent nature, so description adds meaningful 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?

Two sentences, concise and front-loaded with the core purpose. Every sentence adds value with minimal 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?

Covers purpose, data scope, metric, and example. Output schema exists (not shown) reducing need for return value description. No major gaps given tool 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?

Schema describes sort (enum) and limit (1-20 default 10). Description mentions 'top N' and 'ranked', which alludes to these parameters but does not detail them. Schema coverage is moderate, so a 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 it returns brands ranked by depreciation based on UK used-price data, and includes an example question. This distinguishes it from sibling tools which focus on individual valuations or 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?

No explicit guidance on when to use this tool versus alternatives like get_valuation or get_market_health. The example question implies usage for brand-level depreciation queries, but lacks exclusion criteria.

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 the tool as readOnly, openWorld, and idempotent. The description adds valuable behavioral context: the return value includes full details (specs, condition, frame number, photos, delivery, seller's city) and the source of the slug. No contradictions 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?

Two sentences that front-load the purpose and follow with concrete usage guidance and an example. Every sentence adds value, 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 presence of an output schema (not shown but indicated true), the description does not need to detail return values. It fully covers purpose, data returned, source of required parameter, and a realistic invocation example. With 29 siblings, it is clear when to use 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?

Schema coverage is 100%, with the parameter 'slug' described as a listing URL slug. The description adds provenance: the slug comes from 'search_bikes' or 'get_recent_listings', which aids the agent in chaining calls. This additional context justifies above baseline 3.

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 ('get') and resource ('listing detail') and enumerates the exact data returned (specs, condition, frame number, photos, delivery, seller's city). It clearly distinguishes from sibling tools like 'search_bikes' by requiring a slug from prior 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 description provides an explicit usage scenario: after a user expresses interest in a specific bike, use the slug from a prior result. It implies when to use but does not explicitly mention when not to use or list alternatives, though the context of 29 siblings makes the purpose 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 indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds value by explaining the composite indicator components (days-to-sell, spread, inventory) and stating 'Refreshed nightly.' This provides update frequency beyond 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 very concise: two sentences plus an example. Every word adds value, and the information is front-loaded with the core purpose.

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 provides sufficient conceptual context. It explains the composite indicator and includes an example, but it doesn't detail output format (delegated to schema). Slight improvement could mention intended audience or typical use cases.

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 no parameters, so the description carries full burden. It clearly explains what the tool returns conceptually (a composite market signal), which is essential for an agent to understand the output without depending on parameter descriptions.

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 tool's purpose: 'Buyer's-vs-seller's market signal for the UK used-bike market — should the user buy or sell now?' It specifies the verb (signal), resource (UK used-bike market), and scope. This distinguishes it from siblings like get_market_index and get_price_trends.

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 includes an example ('is now a good time to buy a road bike?') and states when to use (to decide buy/sell). However, it does not explicitly mention when not to use or provide alternatives among siblings, which is a minor gap.

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 specifics: data source (Cyclesite nightly index), refresh frequency, and return format (median+range per category). 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?

Three sentences: purpose, detail, example. Every sentence adds value without waste. Front-loaded with the key verb and resource.

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 zero parameters and existence of an output schema, the description fully covers what the tool returns, data source, refresh frequency, and example usage.

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?

No parameters exist, so the description does not need to add parameter meaning. Baseline score of 4 is appropriate; the description does not contradict or miss anything.

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 returns UK used-bike market prices by category (road, mtb, etc.) with median and range, distinguishing it from sibling tools like get_price_trends or get_valuation.

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

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

The description provides an example query ('how does the UK used-bike market look right now?') and context about data freshness, but does not explicitly state when not to use or compare with alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds context by stating it is 'reference data — refreshed when models are added or specs change', which explains the openWorldHint (data may change over time) and the read-only nature. It also mentions 'AI-generated description', implying non-deterministic generation but idempotent for same inputs. No contradictions 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, all of which add value: the first sentence states the tool's purpose and output content, the second explains data freshness, and the example clarifies usage. No redundant or unnecessary words.

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 (not shown), the description does not need to document return values. It covers the tool's input (brand, model), output content categories, and update behavior. The mention of 'AI-generated description' is a notable behavioral trait. The description is sufficiently complete for a reference data 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?

Input schema has two string parameters (brand, model) with 0% description coverage. The description partially compensates by providing an example ('Specialized Allez'), which indicates the parameters but does not specify valid values, formatting, or constraints. Given the low coverage, more explicit parameter guidance would be needed for a higher score.

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 returns a catalogue entry for a brand and model, listing specific content categories (category, year range, AI-generated description, key specs, market summary). It distinguishes from sibling tools like get_listing_detail or get_spec_sheet by focusing on static reference data, and the example 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 description specifies it is reference data that refreshes when models or specs change, indicating it is for static model information. The example 'tell me about the Specialized Allez' provides a clear usage scenario. However, it does not explicitly contrast with siblings like get_spec_sheet or search_bikes, which could be alternative tools for more detailed or dynamic 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 read-only and idempotent behavior. The description adds the OAuth scope requirement, which is beyond annotations. No contradictions, and the example provides operational context. Missing details like pagination or filtering behavior are minor given the schema.

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

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

The description is very concise: two sentences and an example. Every sentence adds value with no redundancy. Purpose 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?

Given the output schema exists, the description doesn't need to explain return values. It covers the tool's purpose and auth requirement. However, it lacks comparison to siblings like 'respond_to_enquiry' or guidance on when no enquiries exist, which would be helpful.

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 describes limit (1-20) but not listingId. The tool description's example hints at filtering by listing but doesn't explicitly explain parameters. With 50% schema coverage, the description adds no additional meaning beyond the schema, meeting the baseline.

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

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

The description clearly states the tool shows buyer enquiries on the authenticated user's listings, with a specific example. It distinguishes from siblings like make_enquiry and respond_to_enquiry by focusing on listing/viewing rather than creating or responding.

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 mentions required OAuth scope and provides an example, implying usage context. However, it lacks explicit guidance on when to use this tool versus related siblings (e.g., when to view vs. respond) or conditions like no enquiries exist.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description adds value by specifying the required OAuth scope ('listings:read') and providing a usage example. 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?

Three sentences, each earning its place: first states purpose, second explains usage patterns, third provides example and OAuth requirement. No wasted words.

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 parameters (2, both optional), presence of output schema, and annotations, the description covers usage patterns, OAuth scope, and an example. It's fully complete for a 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that threadId comes from a prior get_my_messages list or make_enquiry, and that omitting it lists all threads, which goes beyond the schema's brief descriptions.

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 reads the buyer's own Cyclesite message threads and seller replies, distinguishing between listing all threads and reading a specific thread. This differentiates it from siblings like get_my_enquiries or respond_to_enquiry.

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 specifies calling without args to list conversations or with a threadId to read one thread, and mentions pairing with make_enquiry. While it doesn't explicitly exclude alternatives, the context is clear and provides a usage example.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds 'Monthly data, refreshed at month-end', which details data freshness beyond annotations. 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?

Two sentences: first states purpose, second gives example and data freshness. No redundant words; front-loaded and efficient.

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 (2 params, output schema present), the description covers scope (UK, used-bike), data source, refresh cycle, and example. Doesn't detail edge cases, but output schema handles return structure.

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 covers 50% of parameters (months has description '1-24.', category has none). The description adds 'by category' and 'from Cyclesite's index series', providing context but not enumerating category values. It partially compensates 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 'UK used-bike price trends over the last N months by category, from Cyclesite's index series', with a concrete example. It distinguishes from siblings like 'get_market_index' which covers broader market health, and 'get_depreciation' which focuses on depreciation curves.

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 an example query ('how have road-bike prices changed in 2026?') and notes monthly refresh, giving clear usage context. However, it does not explicitly state when to avoid this tool vs alternatives like 'get_market_index' or 'get_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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds non-obvious behavioral details: listings are 'refreshed every 15 minutes', limited to 'active UK listings', and return 'up to 10' results. This provides useful context beyond what annotations capture.

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 highly concise with no wasted words. Four sentences front-load the core purpose, usage context, parameter hints, and freshness attribute. Every sentence adds 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 tool's simplicity (3 optional params, output schema exists), the description covers purpose, usage, filters, refresh interval, and geographic scope. It does not detail ordering or return structure, but the output schema handles return details. Adequately 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?

Schema description coverage is 67% (limit and maxPrice have descriptions). The description calls out 'Optional category + maxPrice filters' but does not elaborate on the category enum values or usage patterns. Baseline 3 is appropriate since the description adds moderate value.

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

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

The description clearly states the tool retrieves the freshest active UK listings from Cyclesite, up to 10 items. It pairs a specific verb ('get') with a well-defined resource (recent listings) and distinguishes it from sibling tools by focusing on 'what's new' rather than specific filters.

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?

Explicit usage guidance is provided: 'Use when the user asks "what's new today?" or "any new road bikes this week?" rather than for a specific filter.' This tells the agent when to invoke this tool versus alternatives like search 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 declare readOnlyHint/ openWorldHint/ idempotentHint. Description adds valuable context: data from Cyclesite listings, fallback to industry charts. 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 tight sentences plus example. No fluff. Front-loaded with purpose and data source. Every word 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?

With output schema present, description covers source, fallback, and example. No missing behavioral or contextual details for a simple lookup tool.

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

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

Schema coverage 50% (heightCm described, category only enum). Description mentions height and bike category but adds no detail on category values or optionality. Baseline 3 with slight extra context from example.

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 provides frame-size recommendations based on height and bike category, sourced from real UK listings with fallback. Verb+resource ('recommend size') is specific and distinct from siblings like 'get 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?

Example query implies typical use case, but no explicit when-not-to-use or alternatives. Context shows no direct sibling conflicts, so guidance is adequate though not explicit.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds context: data is aggregated from live inventory and catalogue, returns most-common values, with 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 plus an example, no fluff. Purpose, data source, and output fields are front-loaded. Efficient 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?

Given the presence of an output schema, the description sufficiently covers the tool's purpose, inputs, and output. The UK inventory scope is mentioned, and the example aids understanding.

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 has 0% coverage; description only mentions brand+model[+year] implicitly. No format, constraints, or explanation for the year parameter. An example partly compensates but insufficiently.

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 aggregates spec sheets for brand+model optionally year, specifies data sources, and lists returned fields. The example query clarifies typical 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?

No explicit when-to-use or when-not-to-use guidance. The example implies a use case but does not distinguish from siblings like get_model_info or get_buying_guide.

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 significant behavioral context: data sourced from UK market asking prices (not sale prices), refreshed nightly, and returns a price-by-model-year curve with confidence. This goes well beyond 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?

Three concise sentences: tool purpose, returned data, and data source with example. No fluff, front-loaded with key purpose. 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 an output schema exists, the description covers the main return fields and data freshness. It lacks specifics on error handling (e.g., unknown brand/model) and the exact format for model strings, but overall adequate for a simple two-parameter 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 0%, meaning the description must compensate. While the example hints at expected values (e.g., '2022 Trek Domane SL 6'), no explicit definitions or constraints for brand and model parameters are given. The agent may not know exact string formats or required model 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: to get the valuation of a used UK bike. It specifies the resource (used UK bike), the action (get), and the outputs (median, range, curve, confidence, comparable listings). The example reinforces purpose and distinguishes it as the flagship tool for valuations among siblings.

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

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

The description implies usage as the primary tool for bike valuations ('Cyclesite's flagship tool') but does not explicitly state when to use it versus siblings like get_price_trends or get_depreciation. No exclusions or alternative recommendations are provided, leaving the agent to infer suitable contexts.

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 that only categorical judgment is returned, not the underlying score (to avoid gaming), which is important behavioral context beyond annotations. Consistent with readOnlyHint, openWorldHint, and idempotentHint.

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, an example, and a note—all relevant and front-loaded. No unnecessary words.

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 core behavior and constraints. Output schema exists, so the lack of detailed return values is acceptable. Minor missing details (e.g., what 'flags' and 'wins' mean) are not critical given schema coverage.

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

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

Only one required parameter 'slug' with no schema description; the description mentions 'provide the slug' in an example but does not define what a slug is. Coverage is 0%, so the description partially compensates but could be more precise (e.g., 'listing slug').

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 a categorical quality grade (excellent/good/fair/weak) plus wins and flags, distinguishing it from siblings like get_listing_detail or check_stolen. The verb 'grade' is explicit and specific.

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 helps a buyer assess trustworthiness and a seller self-audit, with an example query. It does not explicitly exclude cases or name alternatives, but the sibling list implies specialized use. Slightly better guidance on when not to use would improve.

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 valuable behavioral details beyond the annotations: orders by stock level, returns stock counts as bands, and notes the limitation that Cyclesite does not expose precise inventory. This fully informs the agent about what to expect, and there is no contradiction with 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 concise sentences, each adding essential information. The main purpose is front-loaded, followed by use cases, then a key behavioral detail and an example. No wasted words.

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 3 optional parameters, an output schema, and helpful annotations, the description covers all necessary aspects: what it lists, ordering, filtering, pagination, stock data format, and a concrete example. It leaves no significant 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 input schema has 100% description coverage, so baseline is 3. The description enhances meaning by clarifying that the catalogue is ordered by stock level (affects q and ordering) and that stock counts are bands, adding context that the schema alone 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 defines the tool as a paginated UK bike-brand catalogue with specific verb (list) and resource (brands). It implicitly distinguishes from sibling tools like list_models_for_brand by focusing on brands, and provides an example usage that clarifies its role.

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 states three use cases: validate a brand name, surface options to a user, or paginate the catalogue. This gives clear context, but it does not mention when not to use or name alternative tools, so it misses the highest bar.

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 read-only and idempotent. Description adds pagination behavior and output fields. Does not contradict 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 efficient sentences plus an example, front-loaded with purpose and output. No wasted words.

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 simplicity of the tool and presence of an output schema, description adequately covers input, pagination, and output fields. Complete for agent use.

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 descriptions cover 75% of parameters; description adds minimal extra meaning (e.g., brandSlug origin). Category enum lacks description, but description doesn't compensate.

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 lists models for a brand on Cyclesite, paginated, returning specific fields (names, year ranges, in-stock). Differentiates 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?

Provides an explicit example workflow showing when to use it after list_brands, with category filtering. No explicit when-not-to-use or alternatives, but context 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?

Beyond annotations indicating readOnly, idempotent, and openWorld, the description adds the required OAuth scope, increasing transparency. However, it does not discuss other behavioral aspects like pagination or response format.

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 cover purpose, scope, auth, and usage example with no wasted words.

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 presence of output schema, the description adequately covers key aspects. It could mention result pagination or filtering behavior, but is largely sufficient.

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

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

The description mentions 'draft / active / sold' which aligns with the status enum, adding marginal value. The limit parameter is not elaborated. With 50% schema description coverage, the description does not significantly compensate.

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 'Show the authenticated user's Cyclesite listings' with a specific verb and resource, and distinguishes from sibling tools like search or get_listing_detail by emphasizing personal 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?

It mentions OAuth scope requirement and provides an example utterance, but does not explicitly contrast with alternatives or specify when not to use this tool.

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

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

Discloses that messages are saved to inbox, seller is notified, and there is a daily limit. Also notes the OAuth scope and scope name sharing. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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 with a clear structure: action, outcome, constraints, related tool, scope, example. No unnecessary words, but could be slightly shorter by combining some points.

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 that both parameters are fully described in the schema and an output schema exists, the description covers the key behavioral aspects (saving, notification, daily cap, scope) and provides an example. It is adequately complete for 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?

Schema descriptions already cover both parameters (message length range and listingId source). The description adds context by linking listingId to search_bikes/get_listing_detail and providing an example message, but adds minimal new semantic information 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 sends an enquiry to a seller on behalf of a buyer. It specifies the action and resource, and distinguishes from siblings like get_my_messages for reading replies.

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

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

Provides clear context for when to use (buyer sending enquiry) and mentions constraints like daily cap and OAuth scope. References reading replies with get_my_messages, but does not explicitly list other alternatives.

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

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

Annotations already indicate mutability (readOnlyHint=false) and idempotency. Description adds OAuth scope requirement but does not address irreversible nature or state change details beyond the action itself.

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 plus a code example, no wasted words. Information is front-loaded with the core action.

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 annotations, output schema existence, and 2 parameters, the description covers the main action, optional param, and scope. Missing context about whose listings can be marked sold, but otherwise 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?

Parameter schema coverage is 0%, but description explains salePriceGbp is optional and gives an example with currency. It does not detail listingId beyond being required, but the example clarifies its role.

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 uses specific verb 'Mark' and resource 'listing' as sold, with an example that clarifies the action. It clearly distinguishes from sibling tools like reserve_listing or publish_listing.

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?

Description states required OAuth scope and provides a concrete example, giving clear context for when to use. However, it does not explicitly exclude alternatives or mention when not to use.

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?

Disclosures far exceed annotations: multi-step behavior, photo upload requirement, conditional payment step, idempotency, and OAuth scope. No contradiction with annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false).

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

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

Front-loaded with purpose, followed by a concise step-by-step explanation and an example flow. Every sentence adds value with 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?

Despite high parameter count and low schema coverage, the description fully explains the multi-step workflow, upload process, payment step, and required OAuth scope. The output schema exists, so return values need not be detailed 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%, so the description must compensate. It adds meaning for draftId (omit on first call, returned later) and frameSerial (stolen bike check), and character limits for title and description. However, many parameters like brand, model, and year remain unexplained beyond the schema, which is 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 publishes a Cyclesite listing and outlines the multi-step process. It distinguishes from sibling tools like draft_listing by detailing the specific flow involving photo upload and payment.

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 explicit usage instructions: first call without draftId, then subsequent calls with draftId until step:'live'. It also mentions OAuth scope and idempotency, but does not explicitly state when not to use this tool versus alternatives like draft_listing.

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?

Disclosures beyond annotations: prefers higher-engagement listings, returns up to 5 picks with rationale. Annotations already declare readOnlyHint=true and idempotentHint=true, but description adds curation behavior, which is helpful. 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?

Three sentences: main purpose, behavior (prefers high-engagement, up to 5, rationale), and examples. Front-loaded, no unnecessary words.

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?

Covers core functionality and return format (up to 5 with rationale). With output schema present, return values are handled. Missing edge cases or failure modes, but sufficient for typical use.

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 baseline is 3. The description adds no new parameter-level details beyond schema, though example queries demonstrate typical combinations. Meets adequacy but does not excel.

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 a clear verb (recommend), resource (bikes from Cyclesite's live UK inventory), and constraints (budget and intent). It distinguishes from sibling tools like search_bikes by emphasizing curated picks with rationale, limited to 5.

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

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

Provides example queries that illustrate ideal use cases (e.g., 'a road bike for £1,500 for weekend rides'). However, it lacks explicit guidance on when not to use this tool versus alternatives, leaving some ambiguity.

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, indicating a safe read-only operation. The description adds that it returns a checklist and URL, consistent with no side effects.

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?

Description is one sentence plus an example, concise and front-loaded. However, it could be slightly more structured to separate what it does from examples.

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 an output schema exists, the description explains the return value (checklist and URL) adequately. Missing information about parameter usage but overall sufficient for a guidance 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 has three parameters (brand, model, serial) with no schema descriptions (0% coverage). The description does not explain how these parameters are used or whether they are needed, adding no meaning 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 'Step-by-step guidance for reporting a stolen UK bike' with specific outputs (checklist and URL) and an example query. It distinguishes from sibling tools like check_stolen which is for checking stolen status, not reporting.

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 'my bike was just stolen, what do I do?' implies when to use this tool. However, it does not explicitly state when not to use it or mention alternative tools.

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

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

Annotations include `idempotentHint: true`, `destructiveHint: false`. The description adds value by explaining the 24-hour hold, refundable deposit, and Stripe integration, going beyond annotations 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?

Two sentences plus an example, front-loaded with purpose and key details. No wasted words.

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 output schema exists, description adequately covers behavior and parameters. Could mention output, but output schema handles it.

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

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

Schema coverage is 50% (depositGbp has description, listingId does not). The description compensates by explaining listingId implicitly and adding context about deposit range and payment method via Stripe Checkout.

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 holds a Cyclesite listing for 24 hours to prevent others from claiming, with optional deposit. It distinguishes from siblings like 'publish_listing' and 'draft_listing' by focusing on reservation.

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 use case with an example ('put a hold on that Trek for me'), but does not explicitly mention when not to use or alternatives, though context makes it sufficient.

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 readOnlyHint=false (modification), destructiveHint=false, and idempotentHint=false. The description adds 'Reply to a buyer enquiry' which implies a non-destructive write. No extra behavioral traits are disclosed beyond 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, no extraneous words. The purpose is front-loaded, and the example is compact. Every sentence adds 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?

The description adequately covers purpose, authentication, and gives an example. An output schema exists (though not shown), so return values are covered. It could mention that the tool only works on the user's own listings, but 'authenticated user's listing' implies that.

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

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

Schema coverage is 50% (answer has a description, enquiryId does not). The description does not add detail beyond the schema for the parameters, but the example implicitly shows usage. The description could elaborate on enquiryId.

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 'Reply' and resource 'buyer enquiry on the authenticated user's listing.' It distinguishes from sibling tools like 'make_enquiry' (create) and 'get_my_enquiries' (list).

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 'enquiries:respond' and provides a concrete example of how to use the tool. It does not explicitly state when not to use it, but the example and scope provide good guidance.

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

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

The description discloses that the tool is a write operation (creates a SavedSearch row), requires OAuth scope, and has a proactive notification behavior. It adds context beyond annotations by explaining the alert mechanism and user cap, with 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?

The description is concise yet informative, structured with a clear purpose, behavior explanation, authentication note, examples, and a limit. Every sentence serves a purpose 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?

Given the tool's complexity with 9 parameters and its action of creating alerts, the description covers purpose, behavior, authentication, rate limiting, and provides examples. It is sufficiently complete for an agent to understand 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 description provides examples that implicitly map to parameters like brand, model, and price, but does not add detailed meaning to each parameter. With only 33% schema description coverage, the description partially compensates through usage examples but does not fully clarify all 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 subscribes users to alerts for new listings matching a filter, specifying it will proactively notify about price drops or fresh listings. It distinguishes itself from sibling tools by focusing on alert creation rather than one-time searches.

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?

Examples illustrate typical user queries, and the description mentions OAuth scope and a cap of 50 active alerts. However, it lacks explicit guidance on when not to use this tool or direct comparison with alternatives like search functions.

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 read-only, open-world, and idempotent behavior. The description adds that it returns the canonical OpenAI shape with `id`, `title`, `url`, and suggests a follow-up call. 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?

Three sentences, each with a distinct purpose: compatibility/scope, matching behavior, and output format/next step. No wasted words.

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 single-parameter search tool with an output schema, the description covers the purpose, output shape, and integration with `fetch()`. It's sufficiently complete for an AI agent.

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

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

Schema coverage is 100% with a brief description for `query`. The description adds meaning by explaining what fields are matched (title, brand, model), beyond the schema's 'Free-text query.'

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 active UK used-bike listings by free-text query, specifying it matches title, brand, and model. It distinguishes from siblings like `fetch` and `search_bikes` by noting the output shape and follow-up action.

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

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

The description provides clear usage context: use for free-text search, and then use the returned `id` to call `fetch()`. It doesn't explicitly exclude alternatives, but the hint about the OpenAI shape and the specificity are helpful.

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 the tool as read-only, open-world, and idempotent. The description adds value by stating the result limit (up to 5), data freshness (live/refreshed continuously), and output content (specs and URLs).

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?

Description is three sentences plus examples, all essential. No fluff, well-structured, and front-loaded with key 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?

Given the output schema exists, the description adequately covers purpose, filtering, result limit, data freshness, and examples. Minor omission: does not specify that listings are UK-only, but that is implied.

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 all 6 parameters with descriptions, so baseline is 3. The description only summarizes parameters without adding new semantic depth. Example queries demonstrate usage but do not enhance parameter meaning.

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

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

Description clearly states the tool searches live UK used-bike listings on Cyclesite, specifies filtering options, and output. However, it does not explicitly distinguish from sibling tools like 'search' or 'search_by_location'.

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 when to use (when searching for used bikes on Cyclesite) via example queries, but lacks explicit guidance on when not to use or alternatives among sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable details: radius cap, result limit, ordering by distance, and that it uses live UK marketplace data. No contradictions 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?

Description is four sentences, each adding distinct information: purpose, constraints, output characteristics, and usage example. No redundant content, though the first two sentences could be slightly merged.

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 6 parameters and an output schema, the description covers the core search behavior and constraints effectively. It omits details about category and maxPrice, but these are less critical for understanding the tool's primary function. Output schema is mentioned as existing, so return values are handled.

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 67% (lat, lng, limit, radiusMiles have descriptions; category enums listed but no description; maxPrice missing). The description adds context like radius cap and result limit, but does not fully compensate for missing parameter descriptions. The example hints at usage but doesn't detail parameter semantics.

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 the tool finds Cyclesite listings within a radius of a UK location, with specific constraints like capping at 50 miles and returning up to 10 results ordered by distance. This distinguishes it from sibling tools like 'search' or 'search_bikes' by emphasizing location-based filtering.

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 includes a concrete example with a geocode step, providing clear guidance on when to use the tool. However, it lacks explicit comparison to alternative tools like 'search' for non-location queries, which would make the guidance more complete.

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 tool's safety is clear. The description adds context that same data as get_valuation is used, but no further behavioral details are needed.

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 plus an illustrative example. No unnecessary words, and front-loaded with purpose and context.

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

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

Given the output schema exists and the description mentions the three output values, it is fairly complete. However, it could briefly mention that condition is optional or clarify the output format.

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%, but the description only briefly mentions brand+model+condition. It does not explain parameter values, enumerate condition options, or clarify that year is not a parameter despite appearing in the example.

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 provides seller guidance (asked, floor, ceiling) for a bike's brand+model+condition on the UK market, and specifically frames it as seller guidance versus get_valuation's market value. 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?

Explicitly targets sellers about to list, distinguishing itself from get_valuation. However, it doesn't provide when-not-to-use or alternative recommendations beyond mentioning get_valuation.

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