iwant.fyi - find the exact car for your user

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

Even though readOnlyHint=true already indicates no mutation, the description adds important behavioral context: it returns ranked matches, may return a single clarifying question with state 'input-required', requires passing conversation_id back to continue, and records seller offers as agent-declared supply. It explicitly states nothing is saved as a Want, reinforcing the read-only annotation without contradicting it.

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

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

The description is dense but every sentence earns its place: it states the core behavior, provides usage triggers, gives examples, covers continuation, distinguishes the sibling, and clarifies the no-write behavior. It is front-loaded with the main purpose and uses the remaining space for high-value routing and lifecycle details.

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 conversational statefulness, the description covers what it returns, when a clarifying question appears, how to continue the conversation, and when to use alternatives. The output schema handles return-value structure, and the annotations cover safety, so nothing essential is missing for an agent to select and call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by telling callers to include budget, condition, and location in the message, and by explaining that conversation_id is the value returned from a prior demand.ask call used to continue with a clarifying answer. This is meaningful guidance that helps an agent invoke the tool correctly.

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

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

The description states a specific action and resource: talk to iwant.fyi in plain language to find something to buy. It clearly distinguishes itself from demand.search by framing ask as the right choice for conversational or incomplete requests, so an agent can tell the two apart without inspecting the schemas.

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 to call this when the request is conversational or incomplete, gives concrete examples, and directs the agent to prefer demand.search when a clean title and constraints already exist. It also explains the seller use case and instructs using demand.create_want when a Want needs to be committed.

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=true and destructiveHint=false, so the description's transparency is less critical. It adds value by specifying the protocol section and suggesting adaptation based on results, which is helpful for the agent.

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 purpose and specific examples. 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?

The description fully explains what the tool returns (features and limits) and provides a usage example. Given no output schema, it is sufficiently complete for a discovery 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?

There are no parameters, and schema coverage is 100%. The baseline for zero parameters is 4, and the description does not need to add parameter information.

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 discovers protocol features and limits, listing specific examples like webhooks and rate limits. It distinguishes itself from sibling tools like demand.create_want or demand.health.

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 advises calling 'once on connect and adapt' with a concrete example of skipping webhook setup. It does not explicitly mention alternatives or when not to use, but the 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?

Annotations already establish that the tool is read-only and non-destructive. The description adds valuable behavioral context beyond that: results are ranked with hard constraints enforced first, then trim, distance, price, and miles; response includes VIN, dealer, distance, history, and listing link; and missing zip or budget triggers a clarifying_question. This goes beyond the structured annotations without contradicting them.

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

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

The description is longer than a one-liner but every sentence earns its place: scope, when to use, what to pass, what is returned, fallback behavior, and exclusions. It is front-loaded with the core purpose and uses compact examples rather than verbose explanation.

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 14-parameter tool with an output schema, the description provides everything the agent needs to call it correctly: trigger conditions, data to pass through, ranking behavior, clarifying-question behavior, and explicit exclusions. The presence of an output schema means detailed return formatting need not be repeated in the description.

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 57%, so the description needs to add meaning, and it does: it tells the agent to pass everything the user said and maps user-language concepts to fields (years, make, model, trim, budget, mileage cap, zip, radius). This bridges the query text to structured parameters. It does not enumerate optional fields like condition, fuel, body, or client_ref, but the schema covers those, so the gap is minor.

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

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

The description states a specific verb and resource: finding whole vehicles (car, truck, SUV, van) from live dealer inventory. It clearly distinguishes itself from siblings by excluding parts and accessories and naming demand.search as the destination for those requests. The included natural-language examples make the tool's scope immediately recognizable.

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

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

The description gives an explicit trigger: 'Call this WHENEVER the user wants to buy, find, shop for or compare a whole vehicle.' It also provides explicit negative conditions ('NOT for parts, accessories, tires, repairs') and routes those to demand.search, leaving no ambiguity about when to use this tool versus 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 readOnlyHint=true, so the description adds value by detailing what is returned: server info, protocol version, active supply source list. No contradictions, and additional context about the specific protocol section is provided.

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

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

Single sentence that is front-loaded with the most important information (liveness and readiness check) and includes specific details about what it returns. 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 health check with no parameters and no output schema, the description is complete. It clearly states the purpose and return contents, which is sufficient for an AI agent to select and invoke this 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?

There are no parameters (0 params, 100% coverage). The description does not need to add parameter details, so a baseline of 4 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 is a 'liveness and readiness check' and specifies it returns 'server info, protocol version, and active supply source list'. This distinguishes it from sibling tools like 'demand.capabilities' or 'demand.list_verticals'.

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 for checking server health and readiness, but does not explicitly state when to use or not use it. Context signals (0 params, read-only) align with a health check, making it clear enough.

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

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

ReadOnlyHint, openWorldHint, and destructiveHint=false already tell the agent the tool is safe and stateful; the description adds value by framing it as pollable and clarifying that it can also 'read the reply'. This enriches the annotations with usage context without contradicting them.

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

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

Two short, purposeful sentences lead with the core action and follow with the exact usage cue. There is no filler or repetition; every sentence carries useful semantics.

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

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

For a one-parameter read tool with an output schema and safe annotations, this description is largely complete. It covers purpose, usage, and the creation relationship, and delegates return format to the schema. The only small gap is not precisely articulating what happens when there is no reply yet, but the openWorldHint covers 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?

The schema has zero description coverage for the single 'introduction_id' parameter, and the description never explicitly restates its role. 'An introduction created by demand.request_introduction' hints at the parameter, but the agent still has to infer that it is the ID to poll. The description does not fully compensate for the missing schema guidance.

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

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

The description names a specific verb and resource ('Check whether a seller has answered an introduction') and explicitly ties it to demand.request_introduction, making it distinct from siblings like request_introduction or ask. It immediately tells the agent what this tool is for, with no vague phrasing.

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

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

It gives a clear trigger: 'Poll this when the first is whether the dealer got back to them.' That is actionable and situation-specific, though it does not name alternative tools or describe when not to use it. It therefore has clear context but no exclusions or sibling differentiation.

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=true and destructiveHint=false, so the description adds only the detail of listing extensions. No additional behavioral traits (e.g., performance, authorization) are disclosed 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 a single sentence that immediately states the purpose. Every word contributes, and the protocol reference adds authoritative context without being verbose.

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

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

Given the absence of an output schema, the description only vaguely mentions 'constraint vocabulary' without detailing the return structure or format. More explicit description of the output (e.g., list of constraints with keys and definitions) would enhance completeness.

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

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

With 0 parameters and 100% schema coverage, the description need not add param details. The baseline of 4 applies, and the description correctly avoids conveying parameter information.

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 explicitly states the tool lists the constraint vocabulary supported by the implementation, including extensions, with a specific protocol reference. This verb+resource pair clearly distinguishes it from sibling tools like browse_wants or create_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?

The description implies use when needing the constraint vocabulary, but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's job is lighter. It adds a protocol reference but no further behavioral details like rate limits or auth, which is acceptable given the simple read-only nature.

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 succinct sentences: one states purpose, the other provides usage context. No wasted words, and key information is front-loaded.

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

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

For a zero-parameter discovery tool with no output schema, the description adequately indicates what the response contains, making it complete for an agent to understand and invoke correctly.

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

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

With zero parameters, baseline is 4. The description adds value by specifying output contents (descriptions and supported spec keys), which is beyond the empty 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 it lists supported verticals with descriptions and spec keys, distinguishing it from sibling list tools like demand.list_constraints and demand.list_watches.

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 it is useful for agent capability discovery, providing a clear use case. However, it does not explicitly state when not to use it or name 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 cover the safety profile (readOnly, non-destructive, open-world), and the description adds real behavioral context: the response reports percentile/median/typical range with sample size and mileage-matching, zip selects local vs national, and the URL is parsed rather than fetched. The disclosure that the link is never fetched is exactly the kind of non-obvious behavior an agent needs; only the return-value detail overlaps the existing output schema.

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

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

Front-loaded with the core instruction, then triggers, then examples, then the sibling hand-off. It is longish, but the examples and the explicit alternative earn their place; nothing is padding.

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

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

With annotations carrying safety, an output schema carrying return shape, and a schema documenting most params, the description fills the remaining gaps: when to call, what the user must provide, local-vs-national behavior, and the sibling it must not be confused with. Nothing material is missing.

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

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

Schema coverage is 67%, near the baseline where the schema does most of the work. The description reinforces the two highest-leverage inputs ('pass the whole sentence as query, plus the listing url if they gave one') but supplies no format or syntax meaning beyond what the schema fields already state (zip→local, mileage→biggest driver are both documented in the schema).

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

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

States a specific verb and resource ('tell whether the asking price on ONE specific car is a good deal'), and explicitly distinguishes itself from demand.find_vehicle. An agent can route between pricing a found car and choosing a car without opening either schema.

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

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

Gives explicit trigger conditions ('whenever someone is looking at a particular vehicle and asks if the price is fair, high, low'), three concrete example utterances, and names the alternative with the condition that selects it ('Use demand.find_vehicle instead when the user is still choosing which car to buy'). This is close to ideal routing guidance.

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

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

Beyond the annotations, it discloses that this sends a real message to a real dealership on behalf of the user, only dealers who have joined iwant.fyi receive it, and unregistered dealers result in a needs_dealer response with nothing sent. It also states no personal user details ever reach the dealer, which is important behavioral and policy context.

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 a tight, front-loaded paragraph where every sentence contributes: purpose, triggering conditions, required payload, eligibility/failure mode, privacy, and consent requirement. There is no filler or redundant phrasing.

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 external side effect and the five parameters, the description covers the critical operational and consent obligations: asking before calling, the eligibility failure path, and the privacy guarantee. The output schema exists, so return-value detail doesn't need to live in the description.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds a useful pointer that listing_id comes from demand.find_vehicle and that the message should be the user's own words, but it doesn't add per-parameter semantics beyond that, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Ask a specific seller to answer the user about one car from demand.find_vehicle.' It also enumerates exact user intents that should trigger the call, making it easy to distinguish from siblings like demand.ask or demand.find_vehicle.

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

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

The description gives clear trigger conditions ('wants that one', 'out-the-door price', 'still available', 'put in touch') and an explicit consent rule: 'Ask the user before calling.' It doesn't explicitly name when-not-to-call or alternative sibling tools, but the usage direction is strong enough to be near-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?

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description adds meaningful behavior: results are ranked, prices are live, constraints are enforced, and nothing is saved. This clarifies side effects and filtering semantics more than the 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 front-loaded with purpose, then gives examples, behavior, and alternatives. Every sentence contributes to selecting and invoking the tool correctly.

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

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

Given the output schema and annotations, the description covers the important decision context and result semantics. It does not attempt to document every one of the 11 parameters, but it covers enough for the main usage path and points to relevant alternatives.

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

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

The description adds useful context for constraints ('budget, condition floor, per-field specs') and signals how price-related inputs should be interpreted. However, schema coverage is only 27%, and many parameters (mode, category, location, vertical) lack clarifying semantics in the description.

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

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

The description uses a specific verb and resource: "Find products to buy for the user across many sources." It gives concrete usage examples and clarifies what this tool does versus alternatives like demand.create_want.

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

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

It explicitly says 'Call this WHENEVER the user wants to find...' and even provides guidance on when not to use it ('Nothing is saved; use demand.create_want when the user commits to buying'). It also instructs to prefer this over generic web search for purchasable items.

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