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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavior by disclosing that this is a SOFT delete (the row persists but drops off the listing) and that ownership is required. The idempotency sentence restates the annotation rather than adding to it, keeping this from 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?

Four short sentences, front-loaded with the core action and identifier. The final idempotency sentence largely duplicates the annotation's idempotentHint and is the one mildly redundant piece.

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 covers prerequisites (ownership), effect (soft-delete, removal from listing), retry semantics, and intended use cases. The only gap is not stating the return value or whether the ID becomes reusable, which is minor here.

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

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

Schema description coverage is 100%, so the single attachment_id parameter is fully documented in the schema itself. The description adds only the ownership constraint ('you own'), not new format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb (delete), resource (attachment), ownership scope ('you own'), and identifier type (ULID) in the first sentence. An agent can distinguish this from attach_listing_photo, confirm_attachment_upload, and sign_attachment_upload 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?

Explicitly names two use cases – cleaning up an abandoned signed-but-unfinished upload, or removing an unwanted photo – which routes the agent well versus sibling attachment tools. It lacks any when-not guidance or explicit alternative-tool disambiguation (e.g. 'to remove a photo from a live listing, use update_listing'), so it stops short of a 5.

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

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

Annotations already declare 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 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 only declare readOnly=false, destructive=true, openWorld=true; the description goes well beyond by detailing the async pipeline steps, the returned pipeline ID for progress tracking, and the exact failure mode (unmet readiness checklist, content-moderation-blocked photos). That is rich behavioral context an agent cannot get from the structured fields.

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

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

Three tight sentences, front-loaded with the action and followed by the outcome, return value, and failure condition. No filler; 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 complex async mutation with no output schema, the description covers the workflow, the return (pipeline ID), and the error path well. It stops short of telling the agent how to subsequently track progress (e.g., via get_publish_status) or whether publishing is reversible, which keeps it from a 5.

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?

Single parameter with 100% schema coverage, so the baseline is 3. The description adds only the implicit constraint that the hashid must reference a draft listing, which is marginal added meaning over the schema's 'Hashid of the listing to publish.'

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 (kick off the publish pipeline) and resource (draft listing), plus the full outcome: AI enrichment, market data gathering, transition to Active. The 'draft listing' scoping and the pipeline-ID tracking detail implicitly separate it from update_listing and get_publish_status.

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

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

It implies usage conditions (listing must be a draft) and states a failure condition (unmet readiness checklist), which is helpful. However, it never explicitly says when to call this versus alternatives like get_publish_status or withdraw_listing, nor does it direct the agent to check readiness before calling.

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 already declare non-read-only, destructive, idempotent behavior, so the bar is lower. The description adds real context: invalid fields are rejected with guidance, null clears a field, and the call returns the full updated listing. It stops short of naming permission/auth requirements beyond 'a listing you own'.

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 the action, then the parameter format, then the constraints, then the return value, in four tight sentences with no filler. Every 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 supplies the return contract ('full updated listing') and the failure mode (rejection of non-writable/computed fields with guidance). Nothing an agent needs to call this 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%, so baseline is 3, but the description adds the registry-name convention (attr_* keys), a concrete example map, the enum/multiselect/null conventions, and the cross-reference to get_registry that the schema only restates. The added value is real but partially duplicative of the schema text.

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 precise verb+resource (set broker-authored attributes on a listing you own) and explicitly distinguishes itself from update_listing for hot columns and publish-time computed fields. An agent can route between this and update_listing 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 explicit prerequisites (field names must come from get_registry and be marked writable:true), an explicit exclusion (publish-time computed fields and hot columns -> use update_listing), and the selection rule for enum vs multiselect vs null. When-to-use and when-not-to-use are both 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 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?

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.