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 indicate readOnlyHint=false and openWorldHint=true. The description adds that constraints are 'ENFORCED' and that matching is category-agnostic with ranked results across sources. It also references the protocol spec for more details, enhancing transparency 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 well-structured with the core action upfront, followed by matching details and a protocol reference. It is somewhat long but every sentence adds value; 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 tool with 11 parameters (2 required) and no output schema, the description covers what the tool returns (ranked matches with normalized specs) and the follow-up action. It lacks some edge-case details but is adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 91%, so the schema already explains most parameters. The description adds context for 'constraints.rules' and mentions that constraints are enforced, but does not detail each parameter. It provides modest added value over the schema.

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

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

The description clearly states the tool's core action: 'Buy on behalf of your user: submit what they want to purchase and get back ranked, matched supply in the SAME call.' It uses specific verbs ('submit', 'get back'), resource ('Want'), and distinguishes from siblings like 'demand.search' by emphasizing the create-and-match-in-one behavior.

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 guidance: 'Call this whenever the user wants to buy, shop for, find, or source a product or service.' It also advises to report outcomes via 'demand.record_outcome.' While no explicit 'when not to use' is given, the context and sibling list make 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 show readOnlyHint=false (write), openWorldHint=true (side effects possible), destructiveHint=false. Description adds key behavioral details: persists across sessions, requires webhook_url or polling, and same constraints as 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?

Two well-structured sentences, front-loaded with purpose. Every sentence adds distinct value—no waste. Concisely covers purpose, distinction, usage, and key functionality.

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, and description does not mention the API response (e.g., created watch ID). It tells what to do next (webhook or poll) but omits the immediate return value. Given tool complexity and no output schema, this is a gap.

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

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

Schema has 75% description coverage, but description adds meaning: explains webhook_url purpose, polling alternative, and that constraints are same as search. It also notes enforced constraints, adding value beyond the schema for the non-described 'constraints' object and other params.

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 standing want/watch, distinguishes from one-shot search, and gives explicit use cases ('hard-to-source, used, or out-of-stock items'). It contrasts with sibling demand.search, making the purpose and scope very clear.

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 'Unlike a one-shot search, this persists' and provides alternative: 'otherwise poll demand.list_watches'. Also references same query shape and constraints as demand.search, giving clear guidance on 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 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?

Annotations already provide readOnlyHint=true and destructiveHint=false; description adds that it's ephemeral, category-agnostic, constraint-respecting, cross-source ranked matching, and returns ranked matches with normalized specs. 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?

Two sentences with front-loaded purpose and usage, no redundancy. Every sentence adds value, including the protocol reference. Highly 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 9 parameters, low schema coverage, and no output schema, the description provides high-level behavior (ranking, normalized specs) but lacks some details on how nested parameters like location and constraints are used. Still, it covers the essential context for a search tool.

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

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

Schema description coverage is only 11%, but the description references that parameters follow the same shape as demand.create_want, adding some context. However, it does not explain individual parameters beyond title shape, missing details for location, constraints, etc.

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

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

The description clearly states the verb ('Find') and resource ('matching products/supply'), specifies ephemeral nature, and distinguishes from sibling tool demand.create_want by noting it does not save a Want. Use cases (browsing, comparing, checking availability) are listed.

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 this tool (browsing, comparing, checking availability before commit) and when not to (prefer demand.create_want when user intends to buy and wants attribution). Names the alternative tool directly.

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

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

Annotations already declare readOnlyHint=true, 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.