SPACEXPLORATION

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), it discloses server-side fetching, auto-generated thumbnail/hero/full variants, content moderation, the moderation_status values, and the fact that a rejected/escalated photo blocks publishing. That is exactly the consequence-level detail an agent needs.

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

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

The core action and its single-call advantage are front-loaded, and the remaining sentences cover constraints and moderation outcomes. It is dense rather than padded, though a touch long for a two-parameter tool.

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 compensates by describing the returned snapshot and moderation_status/moderation_reason fields, plus the publishing impact. Nothing an agent needs to invoke it correctly 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 coverage is 100% and both parameters are fully documented there, so the baseline is 3. The description restates the https/routable-host constraint already in the schema rather than adding new meaning, so it does not exceed the 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?

States a specific verb (attach) and resource (photo to a listing you own) and explicitly contrasts the single-call URL ingestion with the separate 'sign/upload/confirm' flow, which lets an agent distinguish it from sign_attachment_upload and confirm_attachment_upload without opening their schemas.

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 frames when to use this tool — direct ingestion from a public URL rather than the multi-step sign/upload/confirm path — and states acceptance conditions (https, publicly routable host). It doesn't name the sibling tools outright, so the routing 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?

Adds real behavioral context beyond the annotations: it verifies the stored object against what was signed on size and content-type before marking the attachment ready, and describes the returned snapshot including public variant URLs. Idempotency is repeated from idempotentHint but is made concrete ('returns the same snapshot'). It stops short of saying what happens on a verification mismatch or whether any auth/ownership check applies.

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 and its precondition, then behavior, then return value, then idempotency. Every sentence carries distinct information 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 one-parameter mutation tool with no output schema, it covers the precondition, the verification behavior, the return shape, and idempotency. The remaining gap is failure semantics (what a size/content-type mismatch produces) and permission requirements, which an agent would need to handle errors 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?

With a single parameter at 100% schema coverage, the schema already documents attachment_id as the ULID from sign_attachment_upload and states the PUT precondition. The description restates essentially the same information, adding no format, validation, or edge-case detail beyond it, so the baseline of 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+resource ('Finalize/confirm an out-of-band upload') and places it precisely in the workflow after the bytes have been PUT to the presigned URL. This distinguishes it cleanly from the sibling sign_attachment_upload, which produces the URL and id rather than finalizing.

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 sequencing guidance: confirm only after the file bytes have been successfully PUT to the presigned URL, and it names the source of the id (sign_attachment_upload). It does not state any when-not conditions (e.g., what to do if the upload failed or the object was already confirmed outside the tool), 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 cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely useful behavior: the exact return shape (full listing with hashid and status) and retry semantics. It stops short of explaining permissions required or what the draft state implies next, so it is not fully exhaustive.

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 front-loaded sentences with no filler: purpose, return shape, then retry safety. The idempotency explanation is somewhat duplicated by the schema, which keeps this from being a clean 5, but nothing is wasted.

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 14-parameter, 9-required creation tool with no output schema, the description usefully describes the return payload (hashid, status) and idempotency window. It does not address the required-vs-optional split or draft lifecycle, but the schema and annotations cover the rest adequately.

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 of the 14 parameters documented inline, so the schema carries the load. The description restates the idempotency_key behavior rather than adding syntax or edge cases beyond it, giving baseline value only.

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 a new draft listing'), and the word 'draft' distinguishes it from publish_listing and update_listing. It also states what comes back, so the agent knows this is a creation entry point rather than a mutation of an existing 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?

Usage is implied by the name and by the idempotency_key guidance ('Pass an idempotency_key ... to make the call safe to retry'), but there is no explicit when-to-use/when-not guidance relative to siblings like update_listing or publish_listing. Draft-vs-publish sequencing is left for the agent to 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?

The description adds substantial context beyond annotations: soft-delete semantics, ownership requirements, idempotency behavior, and a non-obvious constraint that a live listing must retain at least one approved photo. These are real operational details not captured by 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?

The description is four tight sentences, front-loaded with the core action and immediately followed by usage guidance and behavioral constraints. Every sentence contributes unique 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 single-parameter destructive mutation with no output schema, the description covers ownership, soft-delete semantics, idempotency, and the critical last-approved-photo constraint. An agent has enough to invoke it correctly and avoid bad orderings.

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% and already documents the ULID parameter and where to obtain it. The description adds an important precondition—the attachment must be owned by the caller—which is not expressed 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 opens with a specific verb and resource: 'Delete an attachment you own by its ULID.' It also clarifies the mechanism (soft-delete) and scope (owned attachments), which distinguishes it from sibling tools like attach_listing_photo or confirm_attachment_upload.

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 names two valid use cases: cleaning up an abandoned signed upload and removing a photo you no longer want. It also gives a concrete ordering constraint for replacing a listing's last approved photo, which is the key alternative workflow.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds context annotations cannot carry: the owner-only authorization rule and the authentication requirement. It stops short of explaining irreversibility or confirm/return behavior.

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, front-loaded sentences with no filler: action, authorization constraint, auth prerequisite. 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 destructive tool with no output schema, the description supplies the key missing context (auth + ownership) while annotations cover the destructive nature. Only lacks detail on post-delete behavior/confirmation, 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?

Schema description coverage is 100%, and the schema itself documents that 'id' is the numeric ID sourced from list_my_saved_searches. The description only restates 'by its ID,' so baseline 3 is appropriate given the schema does the heavy lifting.

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 (Delete) and resource (saved search) and clarifies the lookup key ('by its ID'). It is unambiguous and clearly distinct from save_search/list_my_saved_searches, though it does not explicitly name a sibling for differentiation.

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?

'Only the owner may delete their own searches. Requires authentication.' gives real prerequisites/restrictions, which is more than nothing. However it does not state when to use this versus alternatives (e.g. vs list_my_saved_searches), so usage is implied rather than spelled out.

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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety and external-lookup behavior are covered. The description adds useful context beyond those annotations by disclosing what fields are returned and that the output is meant to feed create_listing, though it does not discuss geocoding ambiguity, failures, 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?

The description is a single, front-loaded sentence that moves from the core action to the returned components to the downstream create_listing workflow. Every clause earns its place and no information is repeated from the tool title or schema.

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?

There is no output schema, so the description usefully enumerates the return shape: coordinates, structured components, formatted address, and place_id. For a simple one-parameter geocoding tool with full schema coverage and read-only annotations, this gives the agent everything needed to call it and use the result.

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 schema has one parameter with 100% description coverage, including an example address, so the structured data already carries parameter semantics. The description adds no additional syntax or format guidance for the 'address' parameter beyond saying it is free-form and US-specific.

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 ('Geocode a free-form US address') and explicitly enumerates the returned identity fields (street_address, city, county, state, postal_code) plus formatted address and place_id. It distinguishes this tool from the listing-management siblings by tying its output directly to create_listing's required fields.

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 explicit sequencing and routing guidance: 'Use this first, then pass the result straight into create_listing instead of supplying your own coordinates.' That is a clear when-to-use instruction and a named alternative behavior, leaving little 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds output-shape context absent from any output schema: entries carry a `url` and may have a `see` page, and the tool returns grouped content meant to be answered from directly.

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 topical coverage that identifies the tool, then the usage instruction and parameter note. Two dense sentences with little waste, though the long enumeration of topics is slightly 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?

For a single optional-enum, read-only tool with no output schema, the description says enough: what it covers, when to call it, how to use the result, and how to filter. Only the exact return structure is left implicit, which is acceptable for a documentation lookup.

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 enum documents all seven values, so the schema already carries the parameter meaning. The description restates the behavior ('pass topic to read one group; leave it out for all of them') but adds no syntax or semantics beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb+resource (returns FAQ answers about the SPACEXPLORATION platform itself) and enumerates the topical scope: pricing, listing, leads, finding, AI assistants, building data, accounts. This clearly distinguishes it from the many listing/parcel siblings, which operate on user data rather than platform documentation.

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 trigger ('Call this before answering any question about how SPACEXPLORATION works or what it costs') plus post-call behavior ('answer from what it returns', link the url/see page). Strong when-to-use guidance, though it names no explicit when-not condition or alternative 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 already cover the read-only, non-destructive, closed-world profile. The description adds real behavioral context beyond that: broker contact is returned only to users authorised to manage the listing, and those users additionally get lease suites with id/status. That conditional, permission-dependent shaping of the response is genuinely useful 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?

Front-loaded with the core action, then progressively details the return payload. Mostly dense and purposeful, though the trailing clause 'the rows update_listing takes back' is awkward and slightly muddies the lease-suite point.

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 burden of describing returns, and it does so well: parcel data, attribute details, photos, broker documents with filename and download URL, and the auth-gated broker contact and lease suites. Complete enough for correct invocation, with only minor polish left.

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 description coverage is 100% (the schema documents the hashid format and where to find it). The description merely restates 'by its hashid' and adds no syntax or format meaning beyond the schema, so the baseline of 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: 'Retrieve the full details of a single listing by its hashid.' The singular scope implicitly separates it from the list/search siblings (search_listings, list_my_listings), but no sibling is named explicitly, so it falls short of a 5.

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: it is clearly the detail-fetch that follows a search hit or listing URL, and the hashid origin is given in the schema. There is no explicit when-to-use/when-not guidance or named alternative, so it stays at minimum-viable.

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/non-destructive/closed-world, but the description goes further by describing the return contents (FEMA flood zone, EPA records, Census demographics, county public record with numbered sources, live listings) and by asserting no side effects: 'looks nothing up and starts nothing.' With no output schema, that payload enumeration carries real weight; it stops short of describing errors or behavior when the hashid is unknown/stale.

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 core action and the origin of the identifier, then the payload, then the usage trigger. It is on the long side and the long enumeration of returned data types borders on padding, but every clause informs retrieval or invocation.

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 one-parameter read tool with full annotation coverage and no output schema, the description supplies the missing return-shape summary, the identifier provenance, and the lifecycle link to status.gathering/researching_county_record. Only failure modes (invalid or expired hashid) are 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?

Schema coverage is 100%, so the baseline is 3, and the description adds the second legitimate source of the value: the hashid can come from look_up_parcel's parcel.hashid or be extracted from a building page URL (/parcel/{hashid}/...). That URL-derivation detail is not in the schema and is practically useful.

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

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

The description states a specific verb and resource ('Read a building SPACEXPLORATION already has') and explicitly separates itself from the similarly named sibling: it returns the same payload as look_up_parcel but performs no lookup. An agent can distinguish this from look_up_parcel without opening either 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 names the exact trigger condition ('use it to check on a building whose status.gathering or status.researching_county_record was true') and the precondition (a hashid already in hand). The contrast 'It looks nothing up and starts nothing' tells the agent when to reach for look_up_parcel instead.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the enumerated overall states (pending/running/completed/failed), the notion of a current phase, per-step progress, and failure reasons — which matters since there is no output 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?

Three sentences, front-loaded with the core purpose, then the two modes, then the workflow hook. No filler or repetition; 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?

With no output schema, the description compensates by enumerating what is returned (overall state, phase, per-step progress, failure reason) and covers both invocation modes. Nothing an agent needs to call it correctly 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 coverage is 100% and the single hashid parameter is fully documented in the schema; the description's phrasing ('Pass a listing hashid... Omit the hashid...') largely restates it. Baseline 3 is appropriate since the schema already carries the parameter semantics.

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 ('Get the status of your listing publishes') and clearly distinguishes the two operating modes: single-listing detail vs. cross-listing run list. An agent can tell it apart from siblings like publish_listing or get_listing 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?

Explicitly ties the tool to a workflow ('Use this to track a publish_listing call to completion') and explains the condition that selects each mode (pass hashid vs. omit it). It names the triggering sibling but gives no explicit when-not-use or exclusion 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds that the result is a complete registry listing rather than a filtered subset, but says nothing about size, caching, or stability of the returned schema. Useful addition, but not rich behavioral context.

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, fully front-loaded: the first states what is returned, the second states when to call it. No filler, no restatement 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 input parameters and no output schema, the description must explain the return shape on its own, and it does: fields, types, allowed values, and display labels. The ordering advice toward search_listings closes the loop for an agent deciding whether it needs this call first.

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 and the schema is an empty object at 100% coverage, so there is no parameter semantics burden to carry. Baseline 4 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 ('Returns the full attribute registry') and enumerates exactly what the payload contains: every searchable and filterable field, its type, allowed values, and display label. An agent can distinguish this reference/schema endpoint from mutating siblings like set_listing_attributes 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?

Gives explicit sequencing guidance ('Read this first ... before calling search_listings with attribute filters'), which tells the agent when to invoke it and which sibling it feeds. It stops short of stating when not to call it (e.g. if the attribute set is already known), so it is clear context without 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description still adds genuinely useful behavior the annotations do not convey: this is a transparent intermediate step, and the response contains both a filters payload and optional bounds that encode the 'near <place>' intent. It stops short of noting ambiguity/fallback behavior, so 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?

Two tight sentences with zero filler, and the workflow is ordered the way the agent must execute it (interpret, then forward). No redundancy with the title or annotations.

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 sketches the return shape (filters plus optional bounds). It leaves open how ambiguous or unparseable queries behave, which is the one thing an agent might need before relying on it, but otherwise it is complete for a one-parameter tool.

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

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

Schema coverage is 100% and the single 'prompt' parameter is already documented with a concrete example. The description only restates that the input is the user's raw query, adding no format, length, or syntax detail 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?

The description gives a precise verb+resource+output: 'Translate a natural-language property-search sentence into a structured filter payload compatible with search_listings.' It explicitly names the sibling it feeds into, cleanly distinguishing it from search_listings itself and from listing CRUD tools.

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 prescribes an explicit workflow: pass the user's raw query here, forward the returned filters and bounds to search_listings. The condition selecting this tool over search_listings (natural-language input vs. already-structured filters) is implied clearly by 'pass the user's raw query here' and the compatibility note.

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, destructiveHint=false, openWorldHint=false, closed world). The description adds the authentication requirement, which is genuinely useful, but says nothing about result size, pagination, or ordering.

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, front-loaded sentences with no filler; the scope statement leads and the filter/auth constraints follow. Efficient, though slightly telegraphic.

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 single-parameter list tool with no output schema and full annotation coverage, the description supplies the essentials: scope, optional filter, auth requirement. Missing only minor operational detail such as ordering or pagination.

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 a fully documented enum, so the schema carries the parameter semantics. The description only restates 'optionally filter by status' without adding format or behavior 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+resource (list listings) with clear scope: owned or brokered by the authenticated user. This cleanly separates it from get_listing (single) and search_listings (catalog-wide), though the sibling alternatives are not named 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?

Implies usage via 'owned or brokered by the authenticated user' and notes the optional status filter, but never says when to prefer this over search_listings or get_listing, nor any exclusions. 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the authentication requirement and telling the agent what the results contain (filters and alert schedule), which the annotations do not convey.

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 that names the action, the resource, the returned data, and the auth requirement with no filler. Every clause carries 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?

With no output schema, the description usefully summarizes what comes back (filters and alert schedule), and the auth requirement is disclosed. It is slightly thin on things like result ordering or pagination for a user with many saved searches, but for a zero-parameter read-only list this is close to sufficient.

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; per the baseline for 0-param tools this is a 4. The description correctly refrains from inventing parameter semantics that don't 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 ('the authenticated user's saved searches') with scope, and even names the payload content (filters and alert schedule). The verb clearly separates it from the sibling write operations save_search and delete_saved_search, so an agent can route without opening schemas.

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 by the name and the verb contrast with save_search/delete_saved_search; there is no explicit when-to-use statement, no exclusion of the other search tools (search_listings, interpret_search), and no alternative named. The only guidance offered is the authentication prerequisite, which is a precondition rather than a routing rule.

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 declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, destructiveHint=false, but the description adds crucial context the annotations cannot: the first lookup triggers background data gathering taking a minute or two, with status.gathering or status.researching_county_record flags, and must be polled via get_parcel rather than re-invoked. It also discloses the authentication requirement and that it returns a shareable page URL and live listings, none of which is in 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?

The single sentence is dense and front-loads the core purpose, but the enumeration of data classes is long and the critical async/polling instruction is buried near the end. It is somewhat overstuffed with return-value detail for a tool without an output schema, reducing scannability.

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

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

Given one parameter with full schema coverage, no output schema, and a moderately complex async behavior, the description is fairly complete: it covers what data is returned, the async polling flow, auth requirement, and the shareable URL. It does not detail error behavior (e.g., refused addresses, signed-out errors) or the exact response shape, but for this tool that gap 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?

Schema coverage is 100% and the address parameter already carries a detailed description including a format example and validation rule (road/town/partial refused). The description adds nothing about the address parameter itself, so it is at the baseline for high coverage; no penalty but no credit either.

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 (look up) and resource (US building by street address) and enumerates the data classes returned (FEMA flood zone, EPA records, Census demographics, county public record). It is distinguishable from the sibling get_parcel, which it references as the polling mechanism, but the split of responsibilities between look_up_parcel (initiate) and get_parcel (check progress) is only partially clarified.

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 clear usage context: works for any building regardless of listing status, requires a signed-in account, and explicitly instructs to use get_parcel with the returned hashid while status is gathering/researching instead of repeating the lookup. It does not explicitly say when NOT to use it versus geocode_address or search_listings, but the primary when-to-use and the polling alternative are well covered.

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?

Goes well beyond the annotations by disclosing the async pipeline model, the enrichment/market-data steps, the return shape (pipeline ID plus non-blocking `suggestions` with concrete examples), and the exact failure mode (unmet readiness checklist, including photos not cleared by moderation). This is the behavioral detail the destructiveHint and openWorldHint flags don't convey.

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 returns, then failure conditions. No filler and each sentence 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?

With no output schema, the description carries the return-value burden and does so fully — pipeline ID for tracking plus the `suggestions` payload and its purpose. Combined with the documented failure conditions, an agent has everything needed to call it and relay 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 single parameter (hashid) is fully documented in the schema, so the description adds no meaning beyond it. The description's real value here is about outputs (pipeline ID, suggestions) rather than parameter semantics, 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 ("kick off the publish pipeline") plus the required precondition ("for a draft listing"), which cleanly separates it from get_publish_status, update_listing, and withdraw_listing. The description also names what happens downstream, so an agent knows this is an action, not a query.

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 preconditions — the listing must be a draft and must pass the readiness checklist, and it discloses the failure path. It implies polling via get_publish_status by returning a pipeline ID, but never names that sibling or states explicitly "use get_publish_status to track".

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true; the description earns credit beyond them by disclosing the persistent side effect (recurring email digests) and the authentication requirement. It stops short of covering idempotency or duplicate-name behavior, so 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?

Three short sentences, front-loaded with the action and outcome, with the auth prerequisite last. Every sentence carries distinct information and none 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 3-parameter, no-output-schema mutation tool, the description covers the durable consequence and the auth requirement, which is most of what an agent needs. It omits what happens on name collision or how saved searches are later managed, which would round it out.

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

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

Schema description coverage is 100%, so the schema already explains name, query, and filters thoroughly (including the name-derivation fallback). The description adds no parameter-level detail, so the baseline of 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+resource ('Save the current search as a named alert') and immediately clarifies the resulting artifact is an email-digest subscription. This distinguishes it from siblings like list_my_saved_searches (read-only listing) and delete_saved_search (removal).

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

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

The description implies the context (user wants ongoing alerts for a search), but never states when to use this versus alternatives such as running search_listings/interpret_search again, nor any when-not conditions. Usage is inferred rather than spelled out.

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, non-destructive, closed-world), so the description's added value is the return contract: paginated hits, facet counts, a public url for citation, and listed_at/updated_at stamps. With no output schema, this disclosure is genuinely useful, though pagination limits and rate behavior remain unspecified.

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: purpose, return contract, then the recommended workflow. Purpose is front-loaded and there is 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 5-param, zero-required, fully schema-documented read tool with no output schema, the description supplies the missing pieces: what comes back (hits, facets, citable url, timestamps) and how to sequence it with interpret_search. An agent has everything needed 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%, so page, sort, query, bounds, and filters are already documented in the schema. The description reiterates the bounds-forwarding rule that the schema itself already states ('Forward the bounds returned by interpret_search verbatim'), so it adds little beyond the 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?

States a specific verb and resource ('Search commercial real estate listings') and distinguishes itself from siblings like get_listing and list_my_listings by scope. It also specifies the return shape (paginated hits with facet counts) up front.

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 workflow rule: for AI-driven search, call interpret_search first to convert natural language into structured filters, then pass those filters and bounds here. This names the prerequisite sibling tool and the condition that triggers it.

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 cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description adds genuinely new context: submission works anonymously and a reply only occurs if an email is supplied. It stops short of saying where the ticket goes or what acknowledgement the caller receives, but the anonymity/reply semantics are the important disclosure for this operation.

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 action and recipient, followed by the anonymity/reply condition. Nothing is padded and no sentence is 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 three-parameter, fire-and-forget submission tool with no output schema, the description covers purpose, accepted categories, and contact/reply behavior — everything an agent needs to call it correctly. No return-value explanation is required.

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

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

Schema description coverage is 100%, so the schema already documents email, message (plain text, 5000-char cap) and the category enum with its default. The description only restates the email-for-reply behavior, adding no syntax or format detail beyond the schema. 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?

Names a specific verb (file) and resource (feedback/support ticket) plus the recipient team, and enumerates the accepted kinds (bug, feature request, question). This clearly separates it from every listing-management sibling in the set.

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?

States the contexts in which to use it (bugs, feature requests, questions about the app or this MCP server) and the condition for supplying a contact email. It gives no explicit 'do not use for X' exclusion, but the tool is standalone and the accepted categories effectively bound its use.

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 declare destructiveHint=true and idempotentHint=true; the description goes beyond that by explaining that non-writable fields are rejected with guidance, that null clears but live listings refuse to clear publishing-required fields, and that the response is the full updated listing.

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?

Purpose is front-loaded in the first sentence, and each subsequent sentence covers a distinct rule (field naming, writability, enum/null semantics, return value). The parenthetical-heavy prose is dense but not wasteful.

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 tool with no output schema, the description covers validation, rejection routing, clearing semantics, and the return value. Nothing material 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 coverage is 100%, so the baseline is 3. The description adds value by tying attributes to the get_registry writable flag, showing the attr_ naming convention, and specifying multiselect arrays and null-clear behavior.

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 (set), resource (broker-authored attributes), and scope (a listing you own). It also routes field-name discovery to get_registry and hot-column updates to update_listing, which distinguishes it from both 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?

Explicitly states the alternative for non-writable fields ('use update_listing for those') and points to get_registry as the source of valid field names. The ownership requirement is stated, so an agent knows the precondition.

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?

Goes well beyond the annotations by disclosing the out-of-band data flow (bytes go directly to storage, never through this channel), the required follow-up confirmation, the return payload (presigned PUT URL plus headers), and an avatar content-check behavior. These are exactly the operational traits annotations cannot convey.

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-loads purpose, then return value, then the required follow-up call, then supported targets and the avatar caveat. Every sentence contributes distinct information with no redundancy.

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

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

No output schema exists, and the description compensates by describing the returned artifacts (presigned URL, headers, attachment_id). Together with 100% schema coverage and clear workflow sequencing, an agent has everything needed to call the tool and chain 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 coverage is 100%, so every parameter is already documented, including collection routing and attachable_id conventions. The description restates the attachable types and collections but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema carries the load.

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 ("Begin an out-of-band file upload") and immediately clarifies the mechanism: returns a presigned R2 PUT URL. It names the sibling tool confirm_attachment_upload as the next step, so an agent can distinguish this signing step from the confirmation step without opening either 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 a clear two-step workflow: PUT the file, then call confirm_attachment_upload with the returned attachment_id. It also enumerates supported attachable targets (listings, users, pages). It does not, however, explain when to prefer this over the sibling attach_listing_photo, leaving that alternative unaddressed.

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?

Adds substantial context beyond the annotations: omitted suites are deleted, an empty list clears them all, and any update that would leave a live listing unpublishable is 'refused whole' rather than partially applied. It also states the return value ('the full updated listing exactly as stored'), which the annotations do not cover.

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 sentences, front-loaded with the action and the group requirement, then constraints, then return value. Dense but every sentence carries operational information; minor density cost given the tool's complexity.

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, so the description supplies the return contract, plus the destructive and atomic-refusal semantics that matter most for a destructiveHint=true mutation. An agent has enough to call it correctly and predict failure modes.

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 contributes cross-parameter rules the schema cannot express: groups must be sent whole, and the sale/lease switch requires the destination side's price field. It also clarifies the sale_price-vs-price_on_request and per-suite-vs-listing-level pricing relationship.

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?

Opens with a specific verb+resource and enumerates exactly which data groups it touches (parcel, pricing, marketing, suites), which lets an agent separate it from create_listing, set_listing_attributes, and publish_listing without opening schemas. The scope statement 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 strong conditional guidance: pass at least one group, send groups whole, and switch sale/lease in a single call carrying the new side's price. It stops short of naming sibling alternatives (e.g., set_listing_attributes for attributes, publish_listing for go-live), so it is clear context without explicit routing.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds genuinely new behavioral context beyond that: withdrawal is terminal and irreversible, which is more specific than 'destructive' and directly affects agent decision-making. It does not mention permissions or side effects on related data, keeping 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, zero filler, with the primary action and its effect front-loaded and the irreversibility warning immediately after. 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 one-parameter mutation with annotations covering the destructive profile and no output schema, the definition covers what an agent needs to call it safely. Minor omissions remain, such as whether the withdrawn listing is still retrievable via get_listing or what happens to attached photos.

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 a single documented 'hashid' parameter, so the schema already carries the semantics. The description adds no format, source, or lookup guidance for the hashid beyond what the schema states — 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?

The description pairs a specific verb (Withdraw) with a specific resource (a listing) and adds the observable effect — removal from public search — which separates it from reversible siblings like update_listing. The terminal-status note further distinguishes it from create_listing/publish_listing, 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?

It states the condition for use (removing a listing from public search), the condition against reuse (cannot be re-activated), and the named alternative path ('create a new listing instead'). This is explicit when/when-not/alternative guidance rather than implied context.

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