NeedToFind

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

Beyond the idempotentHint annotation, the description discloses real state semantics: closing halts seller responses, and the found flag branches the outcome into 'fulfilled' versus merely 'closed'. It does not address reversibility or whether the ad record is retained, which keeps it short of 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?

Two sentences, no filler, with the core action and its effect front-loaded and the parameter branch second. Every clause carries 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?

For a two-parameter mutation with an idempotency annotation and no output schema, the description covers the action, its effect, and both flag branches. It leaves out only secondary details such as whether the change can be undone.

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 schema already documents both params and a 3 would be the baseline. The description earns above baseline by explaining the consequence of found=true ('marks it fulfilled') and the default branch ('otherwise it is simply closed'), adding outcome meaning the schema does not carry.

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 (wanted ad) with an explicit ownership scope ('one of the user's own'), which cleanly separates it from posting tools like post_want and browsing tools like my_wants/search_wants. An agent knows exactly what this tool operates on 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?

The rationale 'so sellers stop responding' implies when to reach for it (retiring an active ad), but there is no explicit when-not-to-use or named alternative among the siblings. Usage is inferable rather than stated.

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

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

The annotation set only declares idempotentHint=true, so safety-on-retry is already covered. The description adds real value beyond that by disclosing the user-visible consequence (emails stop), but says nothing about permanence, permissions, or whether the alert can be restored.

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 filler; the action and effect come first, and the id-sourcing hint follows. 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?

For a single-parameter, no-output-schema delete tool with an idempotency annotation, the description covers what it does, the effect, and where the id comes from. Only minor gaps remain (permanence/permissions), which are not critical 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?

With 1 parameter at 100% schema description coverage, the schema already documents the id and its source. The description's "Get the id from list_alerts" largely restates the schema rather than adding format or constraint detail, so the baseline 3 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?

Specific verb ("Delete") plus a precisely scoped resource ("one of the user's want alerts"), with the observable effect stated ("so they stop receiving emails for it"). This clearly separates it from siblings like list_alerts and set_alert.

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

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

The description gives a prerequisite for the required id ("Get the id from list_alerts"), which is useful usage context. However, it never states when to prefer this over alternatives (e.g., close_want vs delete_alert) or any conditions/exclusions for deleting.

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 cover the safety profile (readOnlyHint=true), so the description's job is to add context — and it does, disclosing the ownership restriction and the exact content surface returned, including an unread count on the private thread. It omits pagination or volume behavior for what could be a long response list, which keeps it out of 5 territory.

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, zero filler: the first leads with the action and the resource, the second carries the hard constraint. No restatement of the title and no redundant verbs.

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 correctly compensates by enumerating the returned fields, and with one simple parameter the input side is fully covered. What is missing is any hint about result size, ordering, or pagination for a list that could grow large.

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% and the single parameter documents its own provenance ('from post_want or my_wants'). The description adds only the qualifier 'one of the user's own wanted ads,' which reinforces the ownership rule but provides no additional format or lookup semantics 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 and resource ('Read the responses sellers have sent to one of the user's own wanted ads') and enumerates the returned payload (seller name, message, contact details, asking price, photo, private thread, unread count). This is far more specific than the sibling names alone and lets an agent distinguish this received-responses read from neighbors like my_responses or 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 a clear applicability constraint: 'Only works for the user's own ads,' which functions as a when-not condition and tells the agent this cannot be used on others' ads. It stops short of naming an alternative tool (e.g., my_responses for responses the user sent), so it is clear context rather than full routing guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the useful cross-tool fact that returned ids feed delete_alert, but says nothing about ordering, pagination, or whether results are scoped/filtered.

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 with the core action front-loaded and zero filler. The parenthetical about alert contents is compact and informative rather than 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?

With no parameters and no output schema, the description carries the return-value burden and does explain what alerts contain and that ids are included. It omits result ordering or volume, which is a minor gap for such a simple list tool.

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

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

The tool takes zero parameters, so there is nothing for the description to document; baseline 4 applies. No parameter syntax or semantics are missing because none exist.

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 (saved want alerts) and clarifies what an alert consists of (keywords and/or category). It differentiates itself from set_alert/delete_alert by explaining the returned ids, but does not distinguish itself from other list-type siblings such as my_wants or 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?

Usage is only implied: naming delete_alert hints that this is the discovery step before deletion, but there is no explicit when-to-use statement and no mention of set_alert as the creation counterpart. An agent can infer the workflow but must do so itself.

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, so safety is covered; the description adds genuinely new behavioral detail: ordering ('newest first'), the composed return payload (ad + private message thread with buyer + unread count), and the absence of filtering parameters. It doesn't cover pagination or result-size limits, keeping it below 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 verb, scope, and ordering, then appends the use case. No filler, no repetition of the title or name.

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 parameters and no output schema, the description carries the return-shape burden itself, and it does: it enumerates what each entry contains and the sort order. Combined with the annotations covering read safety, an agent has everything needed to select and call this tool.

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

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

There are zero parameters and 100% schema coverage, so the baseline of 4 applies. The description correctly implies the tool is unfiltered, consistent with the empty schema, and adds nothing contradictory.

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 precise verb and resource ('List the responses the user has SENT to other people's wanted ads (as a seller)'), including direction and role, which cleanly separates it from the sibling get_responses (responses received on the user's own ads). An agent can distinguish the two without opening any 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?

It gives a concrete usage context ('Use this to check whether a buyer has replied'), which is a real trigger condition. It does not, however, name alternatives or state when not to use this tool versus get_responses or search_wants, so it stops short of explicit routing guidance.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, so the bar is lower. The description adds useful behavioral detail beyond annotations — status scope ('any status') and ordering ('newest first') — but says nothing about pagination or result limits.

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

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

Two tight sentences, zero waste, with the scope front-loaded and the action guidance immediately following.

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 parameterless read tool with no output schema and annotations covering safety, the description covers purpose, scope, ordering, and a concrete workflow use. The only gap is pagination behavior, which is minor given the tool's 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly omits parameter discussion rather than padding.

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 with scope: 'List the authenticated user's own wanted ads (any status), newest first.' The word 'own' distinguishes it from the sibling search_wants, which covers general searching, so an agent can route correctly without opening a schema.

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

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

Gives explicit use context: 'Use this to find an ad's id before closing it,' tying it to the close workflow. It does not name the alternative (search_wants) or state exclusions, so it stops short of the full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does deliver real behavioral context: sellers respond by email, and the ad persists 30 days unless renewed or closed. It omits permission/auth requirements and any cost or duplicate-listing behavior, so it isn't complete, but the lifecycle disclosure is more than the schema offers.

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 waste, and the core action is front-loaded. Every clause (email responses, 30-day lifetime) conveys information an agent needs.

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 five-parameter creation tool with no output schema and no annotations, the description covers the lifecycle and response channel well. It stops short of stating auth requirements or the return payload, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented with examples and omission rules. The description adds no parameter-level meaning beyond that, which places it at the baseline 3.

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

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

States a specific verb and resource ("Post a wanted ad on NeedToFind") and clarifies the semantics: the user is the buyer looking for something. That distinguishes it from respond_to_want and search_wants, though it never names a sibling explicitly.

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 the verb and the platform context, but no condition selects this tool over alternatives like search_wants or set_alert, and there are no stated prerequisites or exclusions. The 30-day expiry detail hints at lifecycle but doesn't guide tool selection.

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?

With no annotations, the description carries the full burden and does disclose a key side effect: the other person is emailed, plus a caveat to only send user-requested content. It does not mention permissions, reversibility, or error behavior, but the email side effect is the critical disclosure.

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, front-loaded with the action and immediately followed by scope and side-effect caution. Every sentence earns its place 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?

For a two-parameter mutation with no annotations or output schema, the description covers the action, role scope, side effect, and id sourcing. Return values and failure modes are absent, but those are minor for this tool's complexity.

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

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

Schema coverage is 100%, so both parameters are already documented (including the 2000-char limit). The description adds meaningful provenance for response_id by naming the tools that supply it, going beyond the schema's bare 'Id of the response'.

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 ('Send a private message in the conversation on a response') and clarifies it works for both buyer and seller roles, which cleanly separates it from siblings like respond_to_want or post_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?

Gives clear context for use (posting into an existing response conversation) and explicitly routes the agent to get_responses or my_responses for the required response_id. No explicit when-not guidance, but the alternative sources for the id are named.

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?

With no annotations, the description carries the full burden and does well: it discloses the external side effect (the buyer is emailed the message plus contact details) and two operational limits (one response per ad, 20/day). It omits whether auth/user identity is required or whether a response can be withdrawn, but the critical outbound-communication risk is surfaced.

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

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

Three sentences, each earning its place: action, precondition, and limits. The purpose is front-loaded and nothing is repeated from the schema or 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?

For a write-with-external-notification tool with no annotations and no output schema, the description covers the side effect, preconditions, and rate limits well. Minor gaps remain around permission/auth expectations and what the caller sees after success, but an agent has enough to call it 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 description coverage is 100%, with each parameter documented including the id source (search_wants), contact guidance, message length cap, and when to omit asking_price. The description adds essentially nothing beyond the schema, so baseline 3 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?

States a specific verb and resource: responding to someone else's open wanted ad on the user's behalf, with the concrete effect of saying they have the item. It is clear in isolation, but it never differentiates itself from the sibling reply_to_response, a plausible confusion point in this toolset.

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 an explicit precondition ('only use this when the user actually has (or can get) the item and has asked to respond') plus hard constraints (one response per ad, 20 per day). An agent can decide whether to call this without any inference.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's remaining job is lighter. It adds the constraint that only 'open' wants are returned, which is useful scoping, but says nothing about result ordering, pagination, or what an empty result means. Adequate but not rich.

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 zero filler; the core action is front-loaded and the use cases follow immediately. Nothing could be removed without losing 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?

For a read-only, zero-required-param search with a fully described schema and annotation-covered safety profile, the description covers what the tool is and when to reach for it. Only minor gaps remain: what 'open' excludes (closed/fulfilled), ordering, and whether results are paged.

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 limit, query, and category are already fully documented including the enum list and default. The description adds no matching semantics (e.g. whether query is AND/OR across words, or how query and category combine), so baseline 3 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?

States a specific verb (Search) and a scoped resource (open wanted ads on NeedToFind), which distinguishes it from write-side siblings like post_want and from user-scoped ones like my_wants. It stops short of explicitly naming a sibling, so the differentiation is inferable rather than stated.

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 use cases: checking for a duplicate want before posting, and finding wants a user could fulfil. That is clear when-to-use guidance, though it names no alternative tool (e.g. my_wants vs search_wants) and states no exclusions.

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?

With empty annotations the description carries the full burden and does so well: it discloses the notification channel (email), a per-user quota ('Up to 10 alerts per user'), the temporal scope ('Only affects ads posted after the alert is created'), and the matching rule. These are non-obvious behaviors an agent could not infer from the schema.

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

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

Four tight sentences, front-loaded with the core action and trigger, followed by matching semantics, requirements, and limits in descending order of importance. No sentence is 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 two-parameter create tool with no output schema and no annotations, the definition covers purpose, matching logic, quota, and temporal behavior adequately. It omits what the call returns (e.g., an alert identifier) and whether re-creating an identical alert duplicates or replaces one, which would matter for follow-up calls.

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 real meaning: keywords are conjunctive ('Every keyword must appear') and must match in the ad's title or description, which the schema does not specify. It also clarifies that keywords and category are combinable with 'and/or'.

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 (create) and resource (alert) plus the exact trigger condition: the user is emailed when a wanted ad matches their keywords/category. It is unmistakably the creation counterpart to siblings like delete_alert and list_alerts, so an agent can route it without opening any 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?

It gives clear audience context ('for sellers who want to hear about demand for what they have') and the eligibility condition ('Needs at least keywords or a category'), which tells the agent when the tool is callable. It does not name alternatives such as search_wants for one-off searches or delete_alert for removal, and states no when-not-to-use case.

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