iwant.fyi - demand-side commerce

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

Annotations already declare readOnlyHint=true. Description adds behavioral details: pagination, category-agnostic matching, optional wedge filter, returned fields (price, location, category, agent info). 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, front-loaded with the main purpose, no fluff. Efficiently covers purpose, usage, and key output characteristics.

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?

No output schema exists, but description mentions paginated results with specific fields. Covers key filters and behavior. Could mention sorting or pagination parameters explicitly, but sufficient given complexity.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters. Description provides a high-level summary of filters (keyword, category, location, price) but does not add significant detail beyond the schema.

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

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

The description clearly states the verb ('Browse'), resource ('buyer demand/Wants'), and target audience ('seller agent'). It specifies search and filter capabilities, effectively distinguishing it from siblings like search_listings, respond_to_want, etc.

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 states when to use ('discover what users are trying to buy so you can respond with offers'). Clarifies matching behavior ('category-agnostic; wedge filter is optional hint'). Does not explicitly exclude cases, but context is 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 indicate non-read-only mutation. Description simply says 'Create', adding no extra behavioral traits like auth needs, rate limits, or 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?

Two concise sentences with front-loaded action. No redundant 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?

Despite complex tool with 12 params and no output schema, description omits return values, error handling, or success indicators, leaving the agent underinformed.

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 descriptions for all 12 parameters. Description adds no additional meaning beyond schema, so 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?

Description clearly states it creates a seller listing in the iwant.fyi supply directory, distinguishing it from sibling 'create_want' for buyers. Verb 'create' and resource 'listing' are explicit.

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 this when an agent has inventory to sell', providing clear context. However, it does not mention when not to use or list 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?

Discloses it posts on behalf of the owner and returns matches, adding behavioral context beyond annotations. Annotations (readOnly=false, openWorld=true) are consistent; no contradictions. Could mention if auto-accept is possible or if deletion is reversible, but sufficient.

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

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

Two sentences: first states purpose and output, second gives tool preference and requirements. Front-loaded and efficient, 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?

Adequate for a well-documented schema with 88% coverage. Lacks specifics on the match return format and constraints usage, but overall sufficiently describes the tool's role and invocation requirements.

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 88%, so most parameters are already described in the schema. The description only reinforces required fields (title, price, location) and mentions budget/location, adding little new 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?

Clearly states it posts a buyer request on behalf of the owner, with budget and location, and returns matches. Distinguishes from siblings like browse_wants (browsing existing wants) and create_listing (selling).

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 mentions preferring demand.create_want for canonical protocol shape, providing an alternative for agents to consider. Also states required parameters (title, price, location), setting clear 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 provide readOnlyHint=false and destructiveHint=false, and the description adds the ownership restriction. However, it does not elaborate on side effects, reversibility, or authorization requirements beyond ownership. The description adds moderate value 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 concise with two sentences, no redundant words, and front-loads the core action. Every sentence earns its place, and the structure is ideal for quick comprehension.

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 nature of the tool (one parameter, no output schema), the description adequately covers the purpose and key constraint. It could mention whether deactivation is reversible or if there are side effects, but overall it is sufficiently complete for a straightforward cancellation operation.

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 parameter 'watch_id' is fully described in the input schema with a clear origin explanation. The description does not add additional meaning or syntax details beyond what the schema provides. With 100% schema coverage, 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 verb 'Cancel (deactivate)' and the resource 'standing want by id', and distinguishes itself by specifying 'Only your own watches can be cancelled.' This provides a clear and specific purpose that differentiates from sibling tools like 'create_watch' or '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 includes a key usage constraint ('Only your own watches can be cancelled') but does not provide explicit guidance on when to use this tool versus alternatives (e.g., using 'list_watches' to find the ID first). Some usage context is implied but not fully developed.

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 non-destructive behavior. The description adds value by detailing exactly what is discovered (features and limits), providing transparency beyond the annotations. 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 efficiently convey purpose and usage. The first sentence front-loads the key discovery content, and the second provides actionable guidance. No redundancy.

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

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

Given no output schema, the description sufficiently explains what the tool returns (features and limits) and hints at output usage (skipping webhook setup). It is complete for its simple scope.

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 schema coverage is 100%. The description doesn't need to explain parameters but effectively conveys the tool's return semantics through the discovery context.

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

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

The description clearly states that the tool discovers protocol features (webhooks, idempotency, etc.) and operational limits (rate limits, max watches). The verb 'discover' combined with specific examples makes the purpose precise and distinguishes it from siblings like 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 explicitly advises to 'Call once on connect and adapt', including a concrete example of skipping webhook setup if unsupported. This gives clear when-to-use guidance, though it doesn't explicitly contrast with 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 already indicate non-readOnly and non-destructive. The description adds that it returns matches in the same call, respects constraints, is category-agnostic, and provides normalized specs. No contradictions. It adds meaningful behavioral context beyond the annotations.

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

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

Single paragraph of 3 sentences, front-loaded with main purpose. Every sentence adds essential information. No redundancy or filler.

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

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

Given 12 parameters and no output schema, the description explains the return format (ranked matches with normalized specs) and directs to a spec for more detail. It also mentions the next step (demand.record_outcome). Could mention idempotency via client_token, but overall complete enough for an agent to 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?

Schema coverage is high (92%), so baseline is 3. The description adds value by explaining that constraints.rules and condition floors are enforced, and that matching is category-agnostic. This enhances understanding of key parameters like constraints and vertical.

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 records purchase intent and returns matched supply in the same call. It distinguishes from demand.search, providing a specific verb-resource pair and explicit contrast with 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?

Explicitly tells when to use this tool: when user decides to buy or wants a standing want. Also gives an alternative: use demand.search for just finding/comparing. This is ideal guidance for an AI agent.

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 (readOnlyHint=false, openWorldHint=true), description discloses that it creates a persistent watch, posts matches to a webhook, supports idempotency via client_token, and has same constraint behavior as demand.search. No contradiction with annotations.

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

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

Single paragraph front-loading the core concept and usage, with no extraneous information. Every sentence adds value: purpose, persistence, ideal usage, webhook alternatives, and constraint compatibility.

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 complexity (9 params, nested objects, no output schema), description covers core behavior, usage, and constraints reference. Lacks details on error handling or exact match posting format, but overall sufficiently complete for agent 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?

With 78% schema coverage, description adds value by explaining webhook_url behavior, client_token idempotency, and referencing demand.search for constraints. However, some parameters (e.g., description, price_cents) are not elaborated beyond schema, making it slightly above 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?

Clearly states it creates a standing watch that persists across sessions, searches for items, and notifies via webhook or polling. Distinctly contrasts with one-shot search and references demand.search for query shape, distinguishing it from sibling tools like demand.search.

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

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

Explicitly says when to use ('ideal for hard-to-source, used, or out-of-stock items'), how to proceed (provide webhook_url or poll demand.list_watches), and notes constraints enforceability same as demand.search, providing clear guidance on 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 indicate readOnlyHint and non-destructive. The description adds context that the retrieval includes matches and constraints, which is useful behavioral detail beyond the annotations. However, it does not discuss rate limits, authentication requirements, or potential error states.

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, front-loaded with the key action and output. The protocol version reference adds minor noise but does not significantly detract from clarity. Could be more concise by omitting the protocol citation.

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 (one parameter, no output schema, no nested objects), the description is reasonably complete. It specifies the input (want_id) and the output (Want with matches and constraints). However, it could briefly mention what happens if the ID is invalid or the Want is not found.

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 parameter description already provides the meaning (UUID of the want). The description adds no additional semantic value beyond restating the resource type. Baseline 3 is appropriate.

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

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

The description clearly states the verb (retrieve) and resource (a Want by ID), and specifies the scope of the output (including current matches and constraints). This distinguishes it from sibling tools like browse_wants (browsing multiple wants), create_want (creating), and search (querying).

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 does not provide explicit guidance on when to use this tool versus alternatives. It only states what it does, leaving the agent to infer usage context. No mention of when not to use or preferred alternatives.

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

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

Annotations already declare the tool as read-only and non-destructive. The description adds that it returns server info, protocol version, and active supply source list, which provides behavioral context beyond the safety profile. It does not mention potential side effects, but none are expected for a health check.

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 is concise and to the point. It includes a protocol reference that adds context but does not waste words. It is well-structured and front-loaded with the 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?

For a zero-parameter tool with no output schema, the description fully explains the return values (server info, protocol version, supply sources) and the purpose (liveness check). It is complete for the tool's complexity level.

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, so the description adds no parameter information. Per the guidelines, zero parameters gives a baseline score of 4, and the description does not need to elaborate further.

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 that returns server info, protocol version, and active supply source list. This is a specific verb-resource pair (health check) that distinguishes it from all sibling tools, which focus on wants, listings, and 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?

The description implicitly indicates that this tool is used for checking server health and getting protocol information. While it does not explicitly state when not to use or provide alternatives, the context makes its usage obvious, and no sibling tool serves the same 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 indicate readOnlyHint=true and destructiveHint=false, so the description adds limited behavioral context beyond mentioning protocol version and extensions. It does not disclose any new behavioral traits such as rate limits or side effects, but also 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?

The description is a single concise sentence. It front-loads a specific protocol reference which may be unnecessary, but overall it is efficient and not 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 no output schema, the description could elaborate on what the returned constraint vocabulary looks like (e.g., a list of objects with keys). It adequately explains the tool's purpose but lacks detail on output format and expected behavior.

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

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

The tool has no parameters (0 params, 100% schema coverage), so per the baseline rule, a score of 4 is appropriate. The description adds no parameter semantics because there are none, but the mention of 'x_* keys' hints at output structure which is useful.

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

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

The description clearly states the tool lists the constraint vocabulary including extensions, distinguishing it from sibling tools like demand.list_verticals and demand.search. However, it could be more explicit about what 'constraint vocabulary' means for an AI agent.

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

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

No explicit guidance on when to use this tool versus alternatives such as demand.list_verticals or search. The description implies it is for understanding constraints before creating wants or listings, but does not state this clearly.

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

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

Annotations already indicate readOnly and non-destructive behavior. The description adds value by specifying the content returned (descriptions and spec keys), which is sufficient for an agent to understand what to expect.

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

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

The description is two concise sentences with no superfluous words. It front-loads the action and adds a practical usage hint.

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

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

The description covers the return content (verticals, descriptions, spec keys) adequately for a simple list tool. It lacks mention of potential limits or ordering, but this is acceptable given the simplicity.

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

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

No parameters exist, so baseline is 4. 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 it lists supported verticals with descriptions and supported spec keys. It uses specific language and is distinct from sibling tools like demand.list_constraints.

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 notes it is 'useful for agent capability discovery,' providing clear context for when to use it. However, it does not explicitly state when not to use or mention 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=true and destructiveHint=false, so the tool is known to be read-only. The description adds value by stating it returns match count and last checked time, which are not in annotations. No contradictions, and the description complements the safety profile.

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 starts with the verb 'List' and the resource 'this agent's standing wants'. It is concise, front-loaded, and contains no extraneous 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 tool has no parameters, annotations cover safety, and there is no output schema, the description provides all necessary context: what is listed, for whom, and what details (match count, last checked) are included. It is complete for this simple 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 zero parameters, and schema coverage is 100%, so the description does not need to add parameter semantics. The description clarifies the scope ('this agent') and the content returned, which is sufficient for a parameterless tool.

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

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

The description clearly states the tool lists the agent's standing wants (active watches) and includes match count and last checked time. It distinguishes from sibling tools like browse_wants (which likely lists other wants) and create_want (which creates new wants). The purpose is specific and unambiguous.

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

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

The description implies when to use (to view active watches), but it does not explicitly contrast with sibling tools like browse_wants or demand.list_constraints. No guidance on when not to use or prerequisites is provided. It is sufficient but lacks explicit 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 declare readOnlyHint=false and destructiveHint=false. The description adds context about closing the loop and attribution, but does not disclose other behaviors like idempotency, rate limits, or authentication needs.

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

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

Two concise sentences that are front-loaded with the core purpose and protocol reference. No superfluous 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?

Covers the basic purpose and required action, but lacks details on return values, error handling, and usage prerequisites. Given no output schema, more context would be beneficial.

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 71%, but the description enumerates the valid event types, which adds meaning beyond the enum list. It also explains the purpose of want_id and match_id in the context of attribution.

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

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

Clearly states it reports an outcome event against a Want and Match, listing the specific event types. Distinguishes from sibling tools like create_want or browse_wants by focusing on outcome recording and attribution closure.

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?

Indicates the tool closes the demand-signal loop and is required for attribution, implying it should be used after a match and outcome occurs. However, it does not explicitly mention when not to use or provide 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?

The description adds context beyond annotations: 'Nothing is saved', 'Returns matches ranked across all connected commerce sources with LIVE prices and normalized specs', and 'Any constraints you pass are ENFORCED.' This aligns with readOnlyHint and openWorldHint, 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?

The description is concise, front-loaded with purpose, and each sentence adds value. No redundant information, and it efficiently covers purpose, usage, behavior, and protocol reference.

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 missing output schema, the description sufficiently describes return values (ranked matches with live prices, normalized specs). Covers usage, constraints, safety, and distinguishes from siblings, making it complete for this tool's complexity.

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

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

Schema description coverage is only 20%, and the description does not detail most parameters. However, it adds meaning to constraints by explaining enforcement and mentions price, condition, and normalized specs. Still leaves several parameters (mode, category, location, etc.) without explanation, so only partial compensation.

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: 'Find products to buy for the user across many sources.' It uses a specific verb+resource and provides concrete examples. It distinguishes from siblings like demand.create_want and generic web search, making the purpose unambiguous.

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

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

Explicitly instructs to call 'WHENEVER the user wants to find, shop for, compare, price-check, source, or buy a product or service.' Provides examples and contrasts with demand.create_want and generic web search, offering clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, indicating a read operation. The description adds that the response includes 'responses and constraints', which is useful context but does not contradict annotations. No new behavioral traits beyond what annotations already 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, clear sentence that conveys all essential information without any extra words. It is front-loaded with the key action 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?

For a simple retrieval tool with one parameter and no output schema, the description is adequate. It specifies what is included (responses and constraints). However, it could be slightly more complete by hinting at the return format or common 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?

There is only one parameter (want_id), and its schema description ('UUID of the want') covers it completely. The tool description simply says 'by ID', adding no additional meaning beyond the schema. With 100% schema coverage, 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 retrieves details of a specific want by ID, including responses and constraints. It uses a specific verb ('Get') and resource ('want'), and the phrase 'by ID' distinguishes it from sibling tools like browse_wants which list multiple items.

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 no guidance on when to use this tool vs alternatives. Sibling tools exist (e.g., browse_wants, respond_to_want) but no explicit when-to-use or when-not-to-use information is given.

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 agent knows it's safe. The description adds specific behavioral context by listing the data returned (profile, trust score, stats).

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 with no extraneous words, efficiently conveying the tool's 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 zero parameters, annotations covering safety, and no output schema, the description is fully sufficient. It tells the agent exactly what the tool does without needing additional context.

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, so the input schema fully covers what is needed. A baseline score of 4 is appropriate; the description does not add parameter details but none are needed.

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 views the agent's own profile, trust score, and stats, using a specific verb ('View') and resource ('agent profile'). It distinguishes itself from sibling tools which deal with wants, listings, and 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?

The description implies usage when the agent needs to see its own profile, but does not explicitly state when not to use or provide alternatives. No exclusions are mentioned.

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 indicate the tool is not read-only and not destructive. The description adds behavioral context by noting that the response inherits the want's wedge and allows specifying a mode (new/used). It could further disclose constraints (e.g., want must be active), but overall adds value.

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, no wasted words. The first sentence states the core action, the second adds key details. Excellent structure.

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 (4 parameters, no output schema) and available annotations, the description adequately explains the action and key semantics (who responds, wedge inheritance, mode option). It doesn't cover error conditions or prerequisites, but is sufficient for basic selection.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds context only for the 'mode' parameter (inheriting wedge, offered mode). For other parameters, it provides no additional meaning beyond the schema. 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 'Submit an offer/response to an existing want' and explains key details like the agent's owner as responder and that the response inherits the want's wedge. This sharply distinguishes it from sibling tools like create_want or browse_wants.

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

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

The description implies usage when the agent wants to respond to a want, but does not explicitly state when not to use it or suggest alternatives. While the purpose is clear, there is no guidance comparing this to other listing or want 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=true and destructiveHint=false, so the description's additional context about supply directory and filters adds moderate value. However, no behavioral traits beyond annotations are disclosed (e.g., pagination, rate limits, auth requirements).

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, front-loaded with key information. Every part is necessary. 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?

No output schema exists, so description should explain return values or structure. It does not. With 11 parameters and no output details, the description is incomplete for an agent to fully understand the tool's behavior.

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 82%, so baseline is 3. The description lists filter types (full-text, category, wedge, mode, price, condition, location) but does not add meaning beyond schema properties. It does not elaborate on parameter combinations or constraints.

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 searches the supply directory for seller listings, with specific verb 'Search' and resource 'listings posted by sellers'. It distinguishes from sibling tools like browse_wants (which likely browses wants), but does not explicitly differentiate from search_products, which might cause confusion.

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 no guidance on when to use this tool versus alternatives. It lists filters but does not mention context or exclusion criteria. With 14 sibling tools including search_products, such guidance would be valuable.

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 and openWorldHint. Description adds that results are ranked and provides context on data sources and integrations, but does not detail any behavioral constraints beyond what annotations imply.

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

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

Description is concise (two sentences plus a third for alternatives), front-loaded with core purpose, and free of unnecessary detail.

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?

No output schema provided; description only notes 'Returns ranked matches' but omits details on pagination, sort order, or empty results. Given the tool's complexity and lack of output schema, more completeness would be beneficial.

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 good parameter descriptions. The description does not add significant semantic value beyond what the schema provides, so baseline score applies.

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

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

The description clearly states the tool searches for purchasable products across specified sources, with verb 'search' and resource 'products'. It distinguishes from siblings by naming demand.search and demand.create_want as alternatives for structured intent.

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 guidance on when to use this tool vs alternatives (demand.search, demand.create_want) and mentions sources being integrated, helping the agent select correctly.

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