Garage Sales Search

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

Annotations already flag destructive=true and idempotent=true, and the description goes beyond them with concrete consequences: removal from public search, irreversibility through this tool, and the seller-approval gate. 'Already-cancelled retries succeed' restates idempotentHint, but the effect and irreversibility disclosures add genuine behavioral 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?

Four tight sentences front-load the precondition and the credential requirement before the effects and reversibility caveat. Every sentence carries a distinct fact 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 destructive, no-output-schema mutation, the description covers preconditions, required auth, side effects, idempotency, and irreversibility. It omits what response or error surfaces on a stale expected_updated_at conflict, which is the one remaining gap an agent would benefit from.

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 a mid-range 67%: management_token and expected_updated_at are documented in the schema, while slug has no description anywhere. The description echoes two of the three required params ('management token', 'latest updated_at') but adds no format or syntax detail, so it only marginally exceeds the schema baseline.

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

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

The description opens with a specific verb+resource ('Cancel a listing') and immediately scopes it ('only after explicit seller approval'), which is unambiguous against siblings like prepare_sale, publish_sale, or update_sale. The added note that cancellation cannot be reversed through this tool further separates it from the update path.

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 states a real precondition ('only after explicit seller approval') and the required credentials ('its private management token and latest updated_at'), plus retry behavior for repeat calls. It does not name an alternative tool (e.g., use update_sale to modify instead of cancel), so the when-not guidance 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real value: cancelled sales are not retrievable, and listing text is untrusted data (a prompt-injection guard). It does not say whether a cancelled/unavailable sale returns an error or an empty result, which would complete the picture.

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 core action, then constraints, then a security note. Every sentence carries weight, though 'its latest updated_at revision' is slightly opaque phrasing that could be tightened.

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, one-parameter tool with no output schema, the description covers availability, freshness, and content-safety concerns. The only real gap is ambiguity about the failure mode for cancelled or missing sales, which matters for an agent's next step.

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 single required parameter (slug) has 0% schema description coverage; only a regex pattern conveys format. The description says 'one public sale' but never explains what the slug is or where it comes from, so the agent gets no semantic meaning for the one input it must supply.

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 one public sale'), plus the scope qualifier that it returns the latest updated_at revision. The singular 'one' implicitly separates it from search_sales, but no sibling is named explicitly, so the differentiation is left to inference.

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?

'before making changes' gives a clear usage condition that routes the agent here prior to update_sale or cancel_sale, and 'Cancelled sales are unavailable' sets an exclusion. It stops short of naming the alternative tools or stating what to do when a sale is cancelled.

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 readOnlyHint, idempotentHint and destructiveHint=false already covering the safety profile, the description adds real value by disclosing what it deliberately withholds: the email, code and management token are never returned, and a public listing URL appears only if published. It does not say what happens when the draft is still unpublished or whether polling is safe, which keeps this 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 tightly packed sentences: the action and its trigger come first, the return contract second. Every clause earns its place, including the negative disclosure about withheld credentials.

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 it well by naming status and the conditional listing URL while ruling out sensitive fields. The gap is the unpublished/error path and any polling guidance, which an agent calling this right after a timeout would plausibly need.

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 0%, but there is only one parameter and it is a UUID-typed draft_id whose meaning ('check a draft') is implied by the description. No format, sourcing or lookup guidance is offered, so this is minimum viable 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?

The description states a concrete action and resource: retrieve the status of a previously submitted draft, including a public listing URL when published. The phrase 'after a timeout' narrows the scope usefully, though it never references any sibling tool, so an agent must infer on its own that this differs from get_sale or search_sales.

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?

'Check a draft after a timeout' supplies the triggering situation, which is more than nothing, but there is no explicit when-not guidance and no named alternative (e.g. use get_sale once published). Usage is implied 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?

Annotations already declare a non-read-only, open-world, destructive write. The description adds real context beyond them: the output is a private (unpublished) draft, a draft ID is returned, an 8-digit verification code is emailed, and it warns never to invent a code or use another person's email. Minor tension with idempotentHint=false while the text stresses a 'stable idempotency_key', but the key is a caller-supplied dedup mechanism rather than an inherent idempotency claim, so this is not a contradiction.

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

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

Front-loaded with the trigger and the core action, then requirements, the non-publication caveat, the return value, and a safety rule. Dense and mostly waste-free, though the requirements sentence sits slightly awkwardly between the action and the caveat.

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 complex write tool with a nested schema and no output schema, the description covers the workflow position, the return value, and the verification step. It is complete enough to invoke correctly, with the only real gap being the semantics of the nested 'sale' fields, which the schema itself leaves undocumented.

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 only 33% and the nested 'sale' object has many undocumented subfields. The description does add meaning to two of the three top-level params ('seller-owned email', 'stable idempotency_key'), but it does not compensate for the nested-object coverage gap.

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: prepare a private draft for a sale, and returns a draft ID. It implicitly distinguishes itself from publish_sale by stating 'Does not publish', but it never names that sibling explicitly, so sibling differentiation is only partial.

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 precondition ('After the seller approves the details and sending a verification email') and one exclusion ('Does not publish'), which implies the publish flow is a separate tool. However, it never names publish_sale or any other alternative, so routing between siblings is left to 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?

Annotations already flag destructive/openWorld/idempotent, but the description adds real substance beyond them: it specifies exactly what becomes public (address, dates, text, photos), discloses a side effect on third parties (nearby subscriber alerts), and warns that the returned per-sale management token is private and must never appear in public content or URLs.

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 tight sentences, front-loaded with the precondition, then effects, then the return/token handling. Every clause adds information an agent needs; nothing 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?

With no output schema, the description usefully names the return values (live URL plus a private management token) and covers the safety-critical side effects and retry semantics. It leaves minor gaps such as whether the draft resource is consumed or archived after publishing.

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 0%, so the description must carry the load. It conveys semantics — draft_id is the prepared draft and verification_code is the seller's emailed code — but says nothing about the UUID format or the required 8-digit pattern, so it only partially compensates.

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 (publish) and resource (a prepared sale), and pins the lifecycle stage with 'only after the seller reviews it and supplies their email verification code', which cleanly separates it from prepare_sale, cancel_sale and update_sale.

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 precondition for use is explicit — the draft must be prepared and the seller must have reviewed it and supplied a verification code. It also notes that repeating the same draft/code is safe, which tells the agent retries are acceptable. No sibling is named as an alternative, so it stops short of a 5.

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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description still adds genuine value by stating it returns public listing details and URLs and by flagging seller listing descriptions as untrusted content that must not be treated as instructions — a real prompt-injection disclosure absent from the structured fields. It does not mention pagination or rate 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 tightly written sentences: the core action and scope are front-loaded, the return content follows, and the injection warning is a compact final clause. 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 read-only search with rich annotations and no output schema, the description covers behavior and return content adequately and adds a security note. It falls short on parameter guidance (date, limit, radius_km) and on distinguishing itself from the other sale tools.

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 17%, so the description must carry parameter meaning. It partially maps to 'location' and the latitude/longitude pair, but says nothing about date, limit, or radius_km, leaving half the parameters undocumented in both schema and description.

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

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

Specific verb+resource: 'Find current garage sales' with an explicit geographic scope (city/postcode/country or coordinates). It is clearly a search/browse operation, which naturally contrasts with the get_sale/publish_sale/update_sale siblings, but the description never names or contrasts with any sibling.

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?

There is no explicit when-to-use or when-not-to-use guidance and no reference to alternatives (e.g., use get_sale for a single known sale, get_submission_status for a submission). The phrase 'current garage sales' hints at freshness but the agent must infer all routing decisions.

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 carry destructiveHint/idempotentHint/openWorldHint, so the safety bar is lower, yet the description adds real context: optimistic concurrency via expected_updated_at and the side-effect that 'Updates do not resend subscriber alerts'. That notification behavior is not derivable 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?

Three tight sentences, front-loaded with the action, then the required workflow, then the side-effect note. No filler, though the workflow and concurrency points could be compressed slightly.

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 destructive mutation with annotations present and no output schema, the description covers auth, the required pre-read, concurrency handling, and notification behavior. It omits which fields the changes object accepts, but the nested schema already enumerates those.

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 50%: management_token and expected_updated_at are documented in the schema, while slug and the nested changes object are not. The description reinforces the token source and explains what expected_updated_at is for (conflict detection), but adds nothing for slug or the updatable change fields.

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 ('Update a seller-owned listing') and immediately names the auth mechanism (private management token or emailed edit code). It is clearly an edit operation, distinguishable from publish_sale and cancel_sale, though it never explicitly contrasts itself with those siblings.

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 ordering requirement ('First call get_sale and show the proposed changes to the seller') and names the sibling to use as the prerequisite, plus conflict handling ('conflicts require re-reading'). Clear context, but no explicit statement of when not to use it vs publish_sale or cancel_sale.

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