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

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds the important qualification that data is not physically deleted and external copies are untouched, effectively softening 'destructive' into a reversible archive. That is real added value. However, it never says whether an archived listing can be restored, nor what happens if the supplied revision is not current, which is exactly the failure mode an agent needs to anticipate.

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 with no filler, and the operational constraint is front-loaded ahead of the non-deletion clarification. Structure is good; only the density of the first sentence ('only your user's listing with the current revision, after their explicit instruction') packs three separate conditions into one clause chain.

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 output schema, the description covers scope, intent precondition, and the non-destructive nature of the operation. The remaining gaps — revision-mismatch behavior and restorability — are meaningful but narrow, and annotations already carry the destructive/open-world profile.

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 0%, so the description must carry the load for two required parameters. It partially does for 'revision' by implying a must-be-current concurrency check, but says nothing about 'id' being the listing identifier or the expected UUID form. Half the parameter semantics remain undocumented.

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 ('withdraw') and resource ('listing'), plus scope ('only your user's listing') and a precondition ('with the current revision'). The second sentence clarifies that 'withdraw' is an archive, not a hard delete. It does not name a sibling to contrast with, but among the given siblings (get_listing, update_listing, create_listing) the operation is unambiguous.

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

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

Gives two real usage constraints: only the calling user's own listings may be archived, and it must follow the user's explicit instruction — a meaningful directive for an agent to confirm intent first. It does not name an alternative tool or state what to do when the revision is stale, so it stops short of 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?

Annotations already declare openWorldHint=true and destructiveHint=true, but the description adds genuinely non-redundant behavior: this is a two-phase flow that requires the user's browser approval, yields a verification URL and code the agent must hand off, and needs no operator key. It does not contradict the annotations (it never claims a read-only operation), though it says nothing about what happens if the user never completes approval or whether the pending link expires.

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 short sentences, front-loaded with the action, followed by the imperative operating rules and a useful constraint about operator keys. No wasted wording.

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

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

The description conveys the flow and the artifacts returned (URL and code), which matters since there is no output schema, but it leaves the single parameter undocumented and never names finish_connection as the required next step. Adequate for the happy path, incomplete for the full lifecycle.

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

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

There is one parameter, `name`, with 0% schema description coverage, and the description never mentions it. With coverage this low the description is expected to compensate, but it gives no indication of what `name` labels or how it affects the connection.

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 ('Start connecting the user's own Shisha Market account') and the word 'start' implicitly distinguishes it from the sibling finish_connection. An agent can tell this is the initiation step of an account-linking flow 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?

Gives concrete operating instructions: present the verification URL and code, have the user sign in and approve in their browser, and never open or approve the link on their behalf. It omits an explicit pointer to the follow-up step (finish_connection) once the user approves, so the routing guidance is clear but not fully closed.

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 only declare readOnly=false, destructive=true, openWorld=true; the description adds materially different facts — the listing is always created in a pending state, there is no publish or moderation path from this tool, and uploads are restricted to user-selected local images. It does not describe what happens on rejection or consent mismatch, and does not explain the destructiveHint, so it stops short of full behavioral coverage.

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 tightly packed sentences, front-loaded with the action and immediately followed by the consent prerequisite, so the most safety-critical instruction is not buried. Every sentence carries a constraint or prohibition; density is high but 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 9-parameter, 8-required tool with a nested acceptance object, no output schema and thin schema descriptions, the description covers the highest-risk areas (consent provenance, image sourcing, pending outcome). It leaves the optional country parameter and the contactUrl format unexplained, but no critical gap remains 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 description coverage is only 11%, so the description has to compensate and it partially does: it constrains photos (user-selected local files, 1-6, 8 MB combined, adding a minimum the schema lacks) and ties the acceptance/version and fullName fields to get_publication_rules and to the user. Parameters such as title, description, category, city, contactUrl and country still receive no semantic guidance 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 ("Create your user's listing") plus the resulting state ("for moderation"), which separates it cleanly from update_listing and list_my_listings. The follow-on sentence adds scope boundaries (pending only, no publish or moderation capability) so an agent knows exactly what the call does and does not accomplish.

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 preconditions: show the final text, photos, contact and city to the user and obtain each consent via get_publication_rules before calling. It names the alternative sibling to consult and includes negative guidance (never fabricate consent or name, never import someone else's listing or photos), which is exactly the when/when-not coverage this dimension rewards.

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 destructiveHint=true and openWorldHint=true, so the safety profile is known. The description adds the specific consequence beyond the annotations: access is revoked and the locally saved connection is removed, plus a required user-confirmation step. It stops short of saying whether revocation is reversible or requires re-authentication.

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 effect first, then the confirmation requirement. Every clause carries actionable 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 zero-parameter, no-output-schema tool, the description covers the action, its consequences, and the confirmation gate. The only gap is post-disconnect state (whether credentials must be re-established), which an agent could reasonably want.

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 parameterless tool applies. No parameter claims are made that could mislead.

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 effect: revoking this agent's access and deleting the locally saved connection. It is clearly the inverse of connect_account in the sibling list, though it does not name that 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?

It gives one concrete procedural guideline (ask the user first), which is the key precondition for a destructive action. It does not say when disconnecting is appropriate versus re-running connect_account or finish_connection to repair a broken connection.

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

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

Beyond the annotations, it discloses that the token is persisted locally and never returned in output, and that a 'pending' result means the user has not yet approved — both non-obvious behaviors. It does not address idempotency of repeated calls or error/expiry behavior, and given destructiveHint=true it says nothing about what a failed or repeated finish does to existing credentials.

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 carrying distinct load: the action, the security-relevant output behavior, and the state/polling semantics. Nothing is repeated and the triggering condition is front-loaded.

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 covers the essentials an agent needs to call it correctly and interpret a pending result. The remaining gap is failure handling and the destructive implications flagged by annotations, which the description leaves unaddressed.

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 implies all context comes from prior approval state rather than arguments, adding nothing misleading 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?

The description uses a specific verb+resource ('finish the connection') and ties it to the approval step of a browser link flow, so the agent can distinguish it from the initiating step. It never names the sibling it complements (connect_account), so the differentiation is implied rather than explicit.

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

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

It clearly states the trigger condition ('after the user approves the browser link') and gives an explicit operational constraint (do not poll faster than once per 5 seconds). It also decodes the pending state, but never names an alternative tool or states what to do if the flow fails.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered externally. The description adds that the payload is about the connected personal account, but says nothing about what happens when no account is connected (error vs. empty result) or whether the call touches the remote service, which matters given openWorldHint=true.

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 front-loaded sentence with no filler or redundancy. Every word contributes to identifying the resource being returned.

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-only lookup the description is nearly sufficient. The only gap is the absence of an output schema combined with no statement of the returned shape or the not-connected case, which would help an agent interpret results.

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 and the schema has nothing for the description to expand on. No parameter meaning is lost.

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 ('Show') and resource ('which personal account this agent is connected to'), which clearly separates it from connect_account/disconnect_account siblings. It stops short of naming a sibling explicitly, but the read-oriented phrasing makes the contrast obvious.

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: an agent can infer this is the read-side companion to connect_account for checking current connection status. There is no explicit when-to-use, when-not-to-use, or named alternative, and no mention of prerequisites such as whether a connection must already exist.

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 read-only, non-destructive and open-world profile, yet the description adds real value: it declares the access scope (only the authenticated user's listing, not arbitrary listings) and warns that listing text is untrusted data rather than instructions, which is a genuine prompt-injection caution an agent cannot get 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?

Two short sentences, front-loaded with the read action and field list, with the safety note placed second. No filler, though the field enumeration is a slightly dense run-on.

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

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

No output schema exists, so enumerating returned fields is essential and is done here; the untrusted-data warning is a meaningful addition. What is missing is the not-found / not-owned case and any confirmation that access is scoped by ownership, which matters for a lookup keyed only by uuid.

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 single 'id' parameter (uuid) is undocumented structurally. The description implies the id identifies one of the caller's own listings, which is a modest clarification, but it adds nothing about format or behavior for unknown/foreign ids.

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 ... your user's listing') and enumerates what is returned: status, moderator comment, revision and photo IDs. The 'your user's' qualifier separates it from public listing lookups and from siblings like list_my_listings and get_listing_photo, though it never names an alternative directly.

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 is implied — fetch one of the caller's own listings by id — but there is no explicit statement of when to use this versus list_my_listings or get_listing_photo, and no guidance on what happens if the id belongs to another user or does not exist.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context that private pending media is included, which hints at elevated access scope, but it does not describe authentication requirements, return format, or behavior when the photo is missing.

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

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

The definition is a single front-loaded sentence with no wasted wording. It is appropriately brief, though the brevity contributes to the missing usage and parameter detail rather than compensating for it.

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 read tool whose annotations already carry the safety profile, the description is minimally adequate. However, with no output schema and zero schema description coverage, it should clarify the two identifiers and at least sketch what inspection returns.

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 neither 'id' nor 'photoId' is documented anywhere. The description implies one identifier refers to a listing and the other to a photo, but it never states that mapping or the UUID format, leaving both required parameters semantically ambiguous.

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 gives a specific verb and resource ('Inspect a photo of your user's listing') and adds scope with 'including private pending media.' It is clear what the tool does, but it never distinguishes itself from the sibling get_listing tool or explains when to inspect a photo versus fetch the listing.

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 guidance, no prerequisites, and no named alternative among siblings such as get_listing or list_my_listings. The only usage signal is the implied act of inspecting a photo, which the agent must infer.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious context beyond that: these rules are policy that gates publishing, and consent must be per-listing rather than derived from the account connection. It does not say what the rules contain or how to act on them, which keeps 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?

Two sentences, no wasted words, and the timing condition is front-loaded before the consent guardrail. Every clause carries actionable 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 zero-parameter read tool with no output schema and readOnly annotations, the description covers what and when adequately. However, it raises a consent obligation without saying where consent is actually supplied — this tool is read-only and cannot record it — leaving the agent to guess whether create_listing carries the consent flag. That gap matters for a compliance-gated workflow.

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 no parameter semantics to explain and the baseline is 4. The description correctly implies no scoping input is needed by referring to 'current' rules globally.

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 current publication rules and separate consent requirements') and immediately scopes it to the listing workflow, which cleanly separates it from the CRUD siblings like create_listing or update_listing. An agent knows this is a pre-flight read, not a mutation, without opening anything else.

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 timing is given: call it 'before creating or editing a listing', which maps directly onto create_listing and update_listing siblings. It does not name those siblings or state any when-not condition, so it falls short of full alternative routing, but the trigger condition is clear.

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

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

The annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds useful behavioral context by specifying that it includes pending and rejected listings for the connected user, though it does not discuss pagination or response size 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?

It is two tightly written sentences with no wasted wording. The scope is front-loaded and the operational warning follows naturally.

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-only listing tool, the definition covers what is listed, whose listings are returned, and the key post-creation scenario. It could add a brief note on ordering or pagination behavior, but no output schema exists and the tool is simple enough that this is a minor gap.

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

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

There are zero parameters, so parameter semantics are not the burden here. The baseline for a zero-parameter tool is 4, and the description does not need to explain parameter meanings.

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 gives a specific verb and resource: it lists the connected user's listings, with the additional scope of including pending and rejected items. This distinguishes it from get_listing for a single listing and from create_listing for creation.

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 explicitly tells the agent to check listings after an uncertain creation result and warns against blind retries, which is strong situational guidance tied to create_listing. It does not explicitly name get_listing as an alternative or state when not to use this tool.

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 only declare destructive=true, openWorld=true, readOnly=false; the description adds substantial behavior beyond that: omitted fields and photos are preserved, new photos append, keepPhotoIds controls retention, and the listing returns to moderation afterward. The only notable gap is that it never says what happens on a revision mismatch (error shape) or what 'moderation' entails for the user.

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 with no filler, and the primary verb-plus-resource is front-loaded before the constraints. The telegraphic fragments ('Returns to moderation.', 'Omitted fields/photos stay') trade a little readability for compactness but each clause carries distinct 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 destructive, nested-object mutation with no output schema, the description covers the state semantics an agent most needs: partial-update behavior, photo merge rules, moderation re-entry, and revision staleness handling. Minor omissions are the failure mode on stale revisions and the fact that acceptance is mandatory on every call, which only the schema reveals.

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 8% across 12 parameters, so the description must carry the load. It does explain the semantically hard ones — revision currency, acceptance as fresh explicit consent, photos appending, and keepPhotoIds selecting retained photos — but says nothing about the field-level parameters (title, description, price, city, country, category, contactUrl) or how they interact with the partial-update rule.

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 and resource ('Edit your user's listing') and immediately names the three inputs that make the edit valid: current revision, fresh publication consent, and changed fields. It is clearly a partial-update tool, distinguishable from create_listing and archive_listing by implication, 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?

It gives real preconditions — use the current revision, obtain fresh explicit consent, and 'Never retry a stale revision silently' — which is meaningful when-to-use guidance for a mutation. It does not, however, route the agent between this and siblings (e.g. when to archive versus edit), nor state what to do after a revision conflict beyond not retrying blindly.

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