Reverse marketplace: post what you want, search wanted ads, and message sellers privately.
Scored across 13 tools
Each tool targets a distinct resource and action (wants, responses, alerts, categories, search/new feeds). The only near-pairs (get_responses vs my_responses; search_wants vs whats_new) are clearly differentiated by perspective and time in descriptions. No two tools appear to do the same thing.
Most names follow a verb_noun pattern (close_want, delete_alert, list_alerts, post_want, etc.), which is predictable. However, my_responses, my_wants (possessive noun phrases) and whats_new break the verb_noun pattern, creating minor inconsistency.
13 tools is well-scoped for a wanted-ads marketplace, covering buyer and seller flows, alerts, and categories without excess. Each tool has a clear place in the set.
Core lifecycle is covered: post/close/list own wants, search/list new wants, respond/reply, manage responses, alerts, categories. Minor gaps exist: no explicit renew_want despite the description mentioning renewal, and no update_want/edit operation, but agents can work around by closing and reposting.
Close one of the user's own wanted ads so sellers stop responding. Set found=true if the user found the item (marks it fulfilled), otherwise it is simply closed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Id of the wanted ad (from post_want or my_wants) | |
| found | No | True if the user found the item |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false; the description adds real behavioral context by explaining the side effect ('sellers stop responding') and that the two outcomes are fulfillment vs. plain closure. It does not contradict the safe/non-destructive annotations, though it omits any note on reversibility or visibility of the closed ad.
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 compact sentences, front-loading the primary action and its effect before the found-branch detail. No filler and nothing redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, idempotent state-change tool with no output schema, the description covers action, effect, and the branching semantics. It is nearly complete; only the post-close response/visibility behavior is unstated, which is minor here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that found=true marks the ad fulfilled and that omitting it (the default/absent case) simply closes the ad. That resolves the optional parameter's default behavior better than the schema text does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (close) and resource (the user's own wanted ad), and adds the operational outcome 'so sellers stop responding,' which separates it from siblings like post_want, my_wants, and delete_alert. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Conveys implied usage (closing one's own ad) and distinguishes the two terminal states via the found flag, but never names an alternative tool or an explicit when-not-to-use condition. Nothing tells the agent how this differs from delete_alert or why to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one of the user's want alerts so they stop receiving emails for it. Get the id from list_alerts.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Id of the alert (from list_alerts or set_alert) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by explaining the effect of deletion (stops emails for that alert). However, it doesn't explicitly flag that the action is permanent/destructive; annotations cover destructiveness.
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?
One sentence, front-loaded with the action and purpose, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter deletion tool, the description is adequate given annotations cover destructiveness, but it could more explicitly state irreversibility or the effect on existing email subscriptions.
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 100% schema coverage, the parameter is already documented. The description references list_alerts as the id source, which mirrors the schema's description, adding only marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Delete one of the user's want alerts') and adds the effect ('so they stop receiving emails for it'), clearly distinguishing it from siblings like set_alert and list_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the id source by saying 'Get the id from list_alerts,' which guides usage, but it gives no explicit when-to-use/when-not-to-use against alternatives beyond the id source.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the responses sellers have sent to one of the user's own wanted ads: seller name, message, contact details, asking price, photo, and the private message thread with each seller (with an unread count). Only works for the user's own ads.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Id of the wanted ad (from post_want or my_wants) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=false (safe, non-open read), so the bar is lower. The description adds real behavioral context: a per-seller private message thread is included, an unread count is surfaced, and access is restricted to the user's own ads. It omits ordering/pagination behavior, which is why it is not a 5.
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?
A single dense sentence that front-loads the operation and scope, then lists the returned data. Every clause carries information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description compensates well by enumerating the fields returned and disclosing the private thread and unread count. It lacks any statement about ordering, pagination, or the empty case, which keeps it short of complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, and schema coverage is 100%; the schema description even names the source tools (post_want or my_wants) for the id. The description adds only that the ad must be the user's own, so it is baseline-level rather than additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (read) and resource (responses sellers sent to the user's own wanted ad), and enumerates the payload fields returned. An agent can distinguish it from the sibling my_responses (responses the user sent) by the direction of the relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a hard precondition ('Only works for the user's own ads'), which is genuinely useful usage guidance. However, it never explicitly contrasts with or routes to the obvious alternative, my_responses, nor states when not to use it, so selection still requires inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's saved want alerts (keywords and/or category), with ids for delete_alert.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds the useful nuance that returned ids feed delete_alert, but it doesn't mention pagination, ordering, or empty-result behavior. With annotations carrying the safety profile, a 3 is appropriate.
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?
A single tight sentence that front-loads the action and resource, then appends the downstream consumer of the ids. 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 zero-parameter read tool with annotations covering the safety profile, the definition is nearly sufficient. The one gap is that return shape and pagination aren't described, but no output schema exists so this omission is minor.
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, so the baseline is 4. The description adds useful context about what the tool operates on (the user's saved want alerts, keyword/category scoped) even though there is nothing to parameterize.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'List the user's saved want alerts', with a hint at the contents (keywords and/or category). It distinguishes itself from set_alert and delete_alert by describing the read operation, though it doesn't explicitly name those siblings the way a 5 would.
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 phrase 'with ids for delete_alert' implies a workflow: call this to obtain ids needed by delete_alert. However, it doesn't state when to use this versus set_alert or other alert-related siblings, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the categories a wanted ad can be filed under, grouped (for example "Autos" contains "Boats" and "Cars & Trucks"). Use the category names exactly as given with post_want, search_wants, set_alert and whats_new. The list can change, so check it rather than assuming.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description adds genuinely useful non-annotation behavior: the category list is volatile and must not be cached or assumed, which is the kind of context an agent cannot get from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: what it returns, how to use the values, and the volatility caveat. Purpose is front-loaded with the caveat last.
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 no-parameter, no-output-schema lookup tool, this is complete: it defines the resource, gives an example of the grouping, and warns about staleness. Nothing an agent needs to call and correctly consume it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. The description correctly says nothing about parameter syntax and instead spends its words on how the returned names should be consumed downstream.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (categories a wanted ad can be filed under), plus a concrete grouping example ('Autos' contains 'Boats' and 'Cars & Trucks') that makes the return shape tangible. Clearly distinguishable from siblings like search_wants or whats_new, which it references rather than overlaps with.
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 the agent how the output must be used ('use the category names exactly as given with post_want, search_wants, set_alert and whats_new') and adds a when-to-call-again rule ('the list can change, so check it rather than assuming'). This is a full routing + timing instruction, not implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the responses the user has SENT to other people's wanted ads (as a seller), newest first, each with the ad, the private message thread with the buyer, and an unread count. Use this to check whether a buyer has replied.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond structured fields: results are newest-first and each row bundles the ad, the private message thread, and an unread count — which is what lets an agent know a single call answers the 'has the buyer replied?' question.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the operation and scope, followed by the usage cue. No filler, no repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-shape burden and does so: sort order, bundled ad, message thread, and unread count. For a parameterless read-only list tool, this is sufficient for correct invocation and interpretation.
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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool is 4. The description correctly implies no filtering input is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource with scope: responses the user has SENT (as a seller), distinguishing it from the sibling get_responses which handles the received direction. The parenthetical '(as a seller)' resolves the ambiguity of whose responses these are.
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?
'Use this to check whether a buyer has replied' gives a concrete use case tied to the unread count. It does not explicitly name get_responses as the alternative for the opposite direction, leaving that routing to inference from the word 'SENT'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the authenticated user's own wanted ads (any status), newest first. Use this to find an ad's id before closing it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral detail: results are scoped to the authenticated user, include any status, and are sorted newest first.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no waste. The listing behavior is front-loaded and the usage hint follows immediately.
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 list tool with no output schema, the description covers scope, ordering, and purpose adequately. It does not mention pagination or result limits, a minor gap for a listing endpoint.
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 takes zero parameters, so per the rubric the baseline is 4. There is nothing further for the description to clarify about inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (the authenticated user's own wanted ads), plus scope qualifiers (any status, newest first). This clearly distinguishes it from search_wants, which implies broader querying rather than the user's own ads.
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 gives a use case: 'Use this to find an ad's id before closing it,' which links it to the close_want workflow. It stops short of naming alternatives or stating when NOT to use it (e.g., vs search_wants or my_responses).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a wanted ad on NeedToFind: something the user is looking for. Sellers can respond by email. The ad stays live for 30 days unless renewed or closed.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Short name of the item wanted, e.g. "Marantz 2270 receiver" | |
| category | Yes | Best-fitting category | |
| location | No | City/region for local pickup, e.g. "Charlotte, NC". Omit if shipping is fine. | |
| max_price | No | Highest price in USD the user will pay. Omit if open to offers. | |
| description | Yes | Details that help a seller know if they have it: model, condition, color, must-haves. Max 2000 characters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a non-destructive, closed-world create operation, and the description adds genuinely useful lifecycle context that annotations do not carry: the ad stays live 30 days, is renewable/closable, and sellers respond by email. It does not state what the call returns or whether any auth/membership is required, so it is strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no filler, with the core action front-loaded and the post-creation behavior following. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with no output schema and light annotations, the description covers the important non-obvious behavior (durability, renewal/close, response channel). The main omission is what the caller gets back (e.g., ad id/URL) and any posting limits.
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%, including per-field examples and the 2000-character limit, so the schema carries full weight here. The description adds no parameter-level detail beyond the schema, matching the baseline of 3 for well-documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Post a wanted ad on NeedToFind') plus the intent ('something the user is looking for'), which cleanly separates it from siblings like respond_to_want and search_wants. It stops short of naming any sibling explicitly, so it falls just below the top band.
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?
Usage is implied by 'something the user is looking for' but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as respond_to_want or set_alert for related goals. Adequate but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a private message in the conversation on a response. Works for the buyer (replying to a seller) and the seller (replying to the buyer). The other person is emailed, so only send what the user has asked you to say. Get the response_id from get_responses or my_responses.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The message text, max 2000 characters | |
| response_id | Yes | Id of the response whose conversation to post in |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only mark this as non-destructive and closed-world, but the description adds critical behavioral context: the message is private, the other person is emailed, and only user-requested content should be sent. This goes well beyond the annotations and directly informs safe invocation.
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 core action. The second explains scope, the third adds workflow and caution, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter messaging tool with no output schema, the description covers purpose, audience, side effect (email notification), safety caution, and parameter sourcing. Nothing important is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance by telling the agent where to obtain the response_id (get_responses or my_responses), which is not in the schema, while the body parameter remains adequately documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Send a private message in the conversation on a response.' It clarifies the tool's role for both buyer and seller, making it easy to distinguish from initial response tools like respond_to_want.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the audience (buyer replying to seller, seller replying to buyer) and tells the agent where to get the required response_id from get_responses or my_responses. It does not explicitly exclude or compare against sibling tools like respond_to_want, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Respond to someone else's open wanted ad on the user's behalf, saying they have the item. The buyer is emailed the message and the contact details, so only use this when the user actually has (or can get) the item and has asked to respond. One response per ad; limited to 20 per day.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Id of the wanted ad to respond to (from search_wants) | |
| contact | Yes | How the buyer can reach the user: email address or phone number. Ask the user; do not guess. | |
| message | Yes | What the user has: condition, details, how a sale could work. Max 2000 characters. | |
| asking_price | No | Price in USD the user would accept. Omit if open to offers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare openWorldHint=false and destructiveHint=false, so the description carries the real behavioral burden — and does: the buyer is emailed the message plus the user's contact details (an irreversible external side-effect), one response per ad, and a 20/day rate limit. This is exactly the kind of context annotations can't express.
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, no filler, and the action is front-loaded before the caution and the quota. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the action, eligibility, side-effect, duplicate limit, and rate limit — ample for a 4-param mutation tool with no output schema. The only omission is what the agent gets back on success, which the description could briefly note since no output schema exists.
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%, documenting id, contact, message, and asking_price thoroughly, so the baseline is 3. The description adds a little semantic intent ('saying they have the item', 'open to offers' is already in schema), but no real parameter 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?
States a specific verb (respond) on a specific resource (someone else's open wanted ad) on the user's behalf, with the outcome (saying they have the item). The 'someone else's' framing clearly separates it from siblings like reply_to_response and my_responses.
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 when-to-use constraint: 'only use this when the user actually has (or can get) the item and has asked to respond.' It does not name the neighboring alternative (reply_to_response) as an explicit contrast, so not a full 5, but the eligibility condition is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search open wanted ads on NeedToFind. Useful for checking whether someone already posted a similar want, or for finding wants a user could fulfil.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results, 1-25 (default 10) | |
| query | No | Keywords to match in title or description | |
| category | No | Only this category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful scoping detail that only *open* wants are returned (closed/fulfilled ones excluded), but says nothing about result ordering, match behavior, or empty-result handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the resource and its scope front-loaded before the use cases. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter search tool with no output schema, the description covers purpose and intent adequately but omits return shape and ordering, which a search caller would want since no output schema compensates. Adequate, not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with limit, query, and an enumerated category all documented inline, so the baseline is 3. The description adds no matching semantics (e.g., whether query terms are ANDed, whether category and query combine), so it does not exceed the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search open wanted ads on NeedToFind') with the qualifying scope that only open wants are returned. It implicitly separates itself from owned-want siblings like my_wants, but never names them, so an agent must infer the boundary rather than read it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two concrete when-to-use contexts: duplicate-checking before posting a want, and discovering wants a user could fulfil. It stops short of naming an alternative tool or an exclusion, so it is clear context without routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an alert so the user is emailed when someone posts a wanted ad matching their keywords and/or category (for sellers who want to hear about demand for what they have). Every keyword must appear in the ad's title or description. Needs at least keywords or a category. Up to 10 alerts per user. Only affects ads posted after the alert is created.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Only ads in this category | |
| keywords | No | Words that must all appear in the ad, e.g. "yanmar injector" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare openWorldHint=false and destructiveHint=false, so the description carries the real behavioral load and does so well: it discloses the matching rule (every keyword must appear in title or description), the quota, and the non-retroactive scope ('Only affects ads posted after the alert is created'). These are exactly the traits an agent cannot infer from structured fields.
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?
Five tight sentences, front-loaded with the action and outcome, then constraints. The parenthetical use-case clause grounds the tool's audience without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter creation tool with no output schema, the description covers purpose, matching logic, prerequisites, quota, and temporal scope. An agent has everything needed to decide 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 100%, so baseline is 3, but the description adds matching semantics beyond the schema: keywords are AND-combined and must appear in the ad title or description, and category acts as a filter. The enum list itself is left to the schema, which 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?
States a specific verb and resource ('Create an alert') and explains the triggering semantics: an email when a wanted ad matches keywords and/or category. This clearly distinguishes it from siblings like delete_alert, list_alerts, and search_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?
Gives the use context ('sellers who want to hear about demand'), the prerequisite ('Needs at least keywords or a category'), and the cap ('Up to 10 alerts per user'). It does not name an alternative tool for one-off searching, but the when-to-use condition is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List open wanted ads posted since a given time, newest first. Use it to notice new demand without re-running a search: remember next_since from the last call and pass it back as since. Defaults to the last 24 hours; looks back at most 30 days. Optionally limit to one category.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results, 1-25 (default 10) | |
| since | No | ISO 8601 time, e.g. 2026-09-30T12:00:00Z. Only ads posted after this are returned. Default: 24 hours ago; at most 30 days back. | |
| category | No | Only this category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-open-world behavior, so the safety profile is covered. The description adds real behavioral content beyond that: newest-first ordering, a 24-hour default window, and a hard 30-day lookback cap, which constrain how the agent should call it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, each load-bearing: what it returns, why to use it plus the cursor pattern, and the default/limit constraints. The purpose is front-loaded with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, cursor continuation, time bounds, and category filtering for a 3-param read-only tool with no output schema. The only soft spot is that next_since itself is referenced without being formally documented, but the usage pattern is clear enough to act on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by explaining the cursor workflow (next_since returned by a prior call is fed back as since) and restating the default/lookback semantics for since and optional category filtering.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List open wanted ads posted since a given time, newest first') with scope, ordering, and an implicit contrast to the sibling search tool ('without re-running a search'). An agent can distinguish it from search_wants immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear usage context (notice new demand without re-searching) and a concrete operating pattern: remember next_since and pass it back as since. It does not explicitly name search_wants as the alternative for one-off queries, so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
list_categorieswhats_newpost_want1 field changedInput schema / properties / category / enumPrevious value: -[
- "Electronics",
- "Furniture",
- "Clothing & Accessories",
- "Vehicles",
- "Musical Instruments",
- "Sports & Outdoors",
- "Tools & Hardware",
- "Boats & Marine",
- "Collectibles & Antiques",
- "Books & Media",
- "Toys & Games",
- "Other"
-]New value: +[
+ "Antiques",
+ "Appliances",
+ "Arts & Crafts",
+ "Baby & Kid",
+ "Barter",
+ "Beauty & Health",
+ "Bike Parts",
+ "Bikes",
+ "Books",
+ "Business",
+ "CDs / DVD / VHS",
+ "Cell Phones",
+ "Clothes & Accessories",
+ "Collectibles",
+ "Computer Parts",
+ "Computers",
+ "Electronics",
+ "Farm & Garden",
+ "Free",
+ "Furniture",
+ "General",
+ "Household",
+ "Jewelry",
+ "Materials",
+ "Music Instruments",
+ "Photo & Video",
+ "Sporting",
+ "Tickets",
+ "Tools",
+ "Toys & Games",
+ "Video Gaming",
+ "ATV / UTV / Snow",
+ "Auto Parts",
+ "Aviation",
+ "Boat Parts",
+ "Boats",
+ "Cars & Trucks",
+ "Heavy Equipment",
+ "Motorcycle Parts",
+ "Motorcycles",
+ "RVs & Camping",
+ "Trailers",
+ "Wheels & Tires"
+]search_wants1 field changedInput schema / properties / category / enumPrevious value: -[
- "Electronics",
- "Furniture",
- "Clothing & Accessories",
- "Vehicles",
- "Musical Instruments",
- "Sports & Outdoors",
- "Tools & Hardware",
- "Boats & Marine",
- "Collectibles & Antiques",
- "Books & Media",
- "Toys & Games",
- "Other"
-]New value: +[
+ "Antiques",
+ "Appliances",
+ "Arts & Crafts",
+ "ATV / UTV / Snow",
+ "Auto Parts",
+ "Aviation",
+ "Baby & Kid",
+ "Barter",
+ "Beauty & Health",
+ "Bike Parts",
+ "Bikes",
+ "Boat Parts",
+ "Boats",
+ "Books",
+ "Business",
+ "Cars & Trucks",
+ "CDs / DVD / VHS",
+ "Cell Phones",
+ "Clothes & Accessories",
+ "Collectibles",
+ "Computer Parts",
+ "Computers",
+ "Electronics",
+ "Farm & Garden",
+ "Free",
+ "Furniture",
+ "General",
+ "Heavy Equipment",
+ "Household",
+ "Jewelry",
+ "Materials",
+ "Motorcycle Parts",
+ "Motorcycles",
+ "Music Instruments",
+ "Photo & Video",
+ "RVs & Camping",
+ "Sporting",
+ "Tickets",
+ "Tools",
+ "Toys & Games",
+ "Trailers",
+ "Video Gaming",
+ "Wheels & Tires"
+]set_alert1 field changedInput schema / properties / category / enumPrevious value: -[
- "Electronics",
- "Furniture",
- "Clothing & Accessories",
- "Vehicles",
- "Musical Instruments",
- "Sports & Outdoors",
- "Tools & Hardware",
- "Boats & Marine",
- "Collectibles & Antiques",
- "Books & Media",
- "Toys & Games",
- "Other"
-]New value: +[
+ "Antiques",
+ "Appliances",
+ "Arts & Crafts",
+ "Baby & Kid",
+ "Barter",
+ "Beauty & Health",
+ "Bike Parts",
+ "Bikes",
+ "Books",
+ "Business",
+ "CDs / DVD / VHS",
+ "Cell Phones",
+ "Clothes & Accessories",
+ "Collectibles",
+ "Computer Parts",
+ "Computers",
+ "Electronics",
+ "Farm & Garden",
+ "Free",
+ "Furniture",
+ "General",
+ "Household",
+ "Jewelry",
+ "Materials",
+ "Music Instruments",
+ "Photo & Video",
+ "Sporting",
+ "Tickets",
+ "Tools",
+ "Toys & Games",
+ "Video Gaming",
+ "ATV / UTV / Snow",
+ "Auto Parts",
+ "Aviation",
+ "Boat Parts",
+ "Boats",
+ "Cars & Trucks",
+ "Heavy Equipment",
+ "Motorcycle Parts",
+ "Motorcycles",
+ "RVs & Camping",
+ "Trailers",
+ "Wheels & Tires"
+]close_wantdelete_alertget_responseslist_alertsmy_responsesmy_wantspost_wantreply_to_responserespond_to_wantsearch_wantsset_alertFree marketplace where AI agents post haves and wants, find matches, negotiate, and share photos.
Buy and sell with Bitcoin, Monero or Pirate Chain. Listings, Want Ads, offers, escrow.
Private intro network. Say what you need or offer, your agent finds the person, both accept.
Swiss intent exchange for AI agents: wants/offers, match, bid, confirm. Free. No escrow.
Add one secure layer between your agents and this server.
