SPACEXPLORATION

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

With no annotations, the description carries full burden. It indicates the listing is created as a draft and returns the full object, but lacks details on permissions, idempotency, or validation.

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?

One sentence with no fluff, but very brief. Could include more context while remaining concise.

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?

Describes return value, which is important since there is no output schema. However, does not mention error cases, status transition, or prerequisites for a tool with 12 parameters.

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 description does not need to add parameter details. It adds context about the return value but no extra semantic value for individual parameters.

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 clearly states it creates a new draft listing and returns the created object with hashid and status. It distinguishes from sibling tools like update-listing-tool and publish-listing-tool.

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?

No guidance on when to use this tool versus alternatives. It does not mention that this is for initial creation only, while other tools handle updates and publishing.

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?

Discloses ownership constraint and auth necessity beyond the tool name. With empty annotations, it carries the burden well. Does not detail error behavior for non-existent IDs or unauthorized attempts, but for a simple delete that's acceptable.

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 concise sentences convey purpose, constraints, and parameter hint with no wasted words. Front-loaded with the core action.

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, no-output-schema delete tool, the description is complete. It covers what, how (by ID), constraints (owner, auth), and parameter source. No further details are necessary.

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 input schema covers 100% of parameters with a description. The description adds context by noting the ID comes from 'list_my_saved_searches', which enhances understanding beyond the schema alone.

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?

Clearly states 'Delete a saved search' which pairs a specific verb with a distinct resource. Differentiates from siblings like 'save_search' (create) and 'list_my_saved_searches' (list) by specifying deletion via ID.

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?

Specifies owner-only restriction and authentication requirement, providing clear context for when the tool is applicable. Does not explicitly state when not to use or suggest alternatives, but the sibling set makes it obvious.

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 are empty, so the description bears full responsibility for behavioral disclosure. It does not mention read-only nature, rate limits, error handling, or permissions. The only added context is that the output matches create_listing's requirements, but no behavioral traits are revealed.

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, well-structured sentence that conveys all essential information without any superfluous text. Every part serves a purpose: stating the operation, listing outputs, and providing usage context.

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 the tool's simplicity (one parameter, no output schema), the description covers the key aspects: purpose, input type, output structure, and relation to create_listing. It lacks details on error conditions or supported address formats, but for a straightforward geocode tool, it is sufficiently complete.

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 'address' is described in both schema and description. The schema gives a basic definition and example. The description adds context: that the address is US-specific and that the result is intended for create_listing. This adds value beyond the schema's own documentation.

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 clearly states the tool geocodes a free-form US address into coordinates and structured components. It specifies the output fields (street_address, city, county, state, postal_code, formatted address, place_id) and explicitly connects it to the create_listing tool, distinguishing it from sibling 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?

The description provides explicit usage guidance: 'Use this first, then pass the result straight into create_listing instead of supplying your own coordinates.' This tells the agent exactly when to use the tool and what not to do (avoid supplying own coordinates), making it a model of clear guidelines.

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

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

With no annotations provided, the description carries full burden. It discloses that broker contact is included only when authorised and lists the returned components (parcel data, attributes, attachments). However, it does not explicitly state that the operation is read-only or non-destructive, which would be helpful.

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 concise sentences with zero waste. The main action is front-loaded, and every sentence adds necessary 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?

Given the simplicity of a single parameter and no output schema, the description adequately covers what is returned and a conditional behavior. A minor improvement would be to explicitly state it is a read operation.

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 baseline is 3. The description adds value by explaining what a hashid is (e.g., 'a1b2c3d4') and where it can be found (URLs, search hits), which aids in correct parameter selection.

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 clearly states the verb 'retrieve', the resource 'full details of a single listing', and the identifier 'hashid'. It distinguishes from sibling tools like search_listings (which returns multiple) and update-listing-tool (which modifies).

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 usage when one needs full details of a specific listing but does not explicitly mention when to use this tool versus alternatives like search_listings or list_my_listings. No exclusions or conditions are provided.

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 are empty, so the description carries full burden. It discloses the tool is read-only, returns specific status fields, and mentions both modes. However, it lacks details on auth requirements, error handling for invalid hashid, rate limits, or idempotency—though for a simple read operation, the disclosure is adequate.

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: first states the purpose, second explains both usage modes and provides a usage tip. No extraneous words, well-structured, and front-loaded with the most important 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 simple tool with one optional parameter and no output schema, the description explains modes, returned fields, and a use case. It lacks error handling or edge case details but is sufficient for effective use given the tool's simplicity.

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

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

Schema description coverage is 100% with a clear description of the hashid parameter. The tool description repeats the two modes but adds no new semantic information beyond the schema. Baseline 3 is appropriate as schema covers 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?

The description clearly states the tool retrieves status of listing publish pipelines, distinguishes two modes (detailed status with hashid, recent runs without), and lists returned fields (state, phase, per-step progress, failure reason). This differentiates it from sibling tools like publish-listing-tool or get_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?

The description explicitly says to use this tool to track a publish_listing call to completion, and implies not to use it for general listing queries. It explains the two usage modes (with/without hashid) but does not explicitly name sibling alternatives or conditions to avoid.

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?

No annotations provided, but the description is straightforward for a read-only tool with no parameters. It discloses return content but doesn't mention any side effects or permissions, which is acceptable given the simplicity.

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 concise sentences: first states purpose, second provides usage context. No extraneous words, efficient and front-loaded.

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

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

Given no output schema, the description fully explains what is returned (fields, types, allowed values, display label) and how it relates to sibling tool search_listings. Complete for its role.

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?

No parameters exist (0 params baseline 4). The description adds no param info, but schema coverage is 100% trivially, so no need for further elaboration.

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 explicitly states it returns the full attribute registry with fields, types, allowed values, and display labels, and distinguishes itself from the sibling search_listings tool by positioning itself as a prerequisite.

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?

Directly instructs the agent to read this tool first before calling search_listings with attribute filters, providing clear contextual guidance on when to use 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?

With empty annotations, the description carries full burden for behavioral disclosure. It states the translation action but does not mention error handling, ambiguity handling, rate limits, or idempotency. The lack of any behavioral traits beyond the basic action leaves the agent uninformed about potential issues.

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 two sentences: first states purpose, second gives usage instructions. Every sentence adds value without redundancy. It is appropriately short and well-structured.

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 one-parameter tool, the description covers purpose and usage adequately. It lacks explicit detail about the output format, but implies compatibility with search_listings. No output schema exists, so some inference is needed, but overall context is sufficient for a straightforward translation 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% for the single parameter, and both schema and description provide an example. The description adds context by framing the parameter as a 'raw query' and tying it to the translation purpose, but overall meaning is already clear from 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?

The description clearly states the tool translates a natural-language property-search sentence into a structured filter payload, specifying the verb (Translate), the input (natural-language sentence), and the output (structured filter payload compatible with search_listings). This distinguishes it from siblings like search_listings.

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 explicitly instructs to pass the user's raw query to this tool and then forward the returned filters to search_listings, providing clear guidance on when to use it and how it fits into a workflow. It also says 'Use this as a transparent intermediate step,' which helps avoid misuse.

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

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

With no annotations provided, the description carries the full burden. It discloses authentication requirements and the ownership/brokerage filter, but does not mention other traits like rate limits, pagination, or sorting behavior. The behavioral information is partial but not misleading.

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 two sentences, front-loaded with the main action, and contains no unnecessary words. Every sentence serves a purpose.

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 the tool's simplicity (1 optional parameter, no output schema), the description covers the core purpose and the parameter. However, it omits details about return format or potential limitations (e.g., max results). Completeness is high but not fully exhaustive.

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 parameter 'status' is fully described in the schema. The description merely reiterates that filtering by status is possible, adding no new semantic value beyond what the schema already provides. Baseline score 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?

The description clearly states the action (list), the resource (listings), and the scope (owned or brokered by the authenticated user). It also mentions optional filtering by status. This distinguishes it from sibling tools like get_listing (single listing) and search_listings (broader search).

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 mentions 'Requires authentication', but does not provide explicit guidance on when to use this tool versus alternatives like search_listings or list_my_saved_searches. No exclusions or alternatives are named, leaving the agent to infer usage context.

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?

Description states the tool requires authentication but does not explicitly declare it as read-only or mention side effects. Without annotations, the description provides minimal behavioral context beyond authentication and result contents.

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 core action and scope, then a second sentence on requirement. No unnecessary words, highly efficient.

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 no parameters or output schema, the description is mostly complete: it specifies the action, scope, and authentication. Could optionally mention that it returns all saved searches without pagination, but not critical for usage.

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?

No parameters exist, so baseline is 4. Description adds context by specifying the scope (authenticated user) and what is included (filters and alert schedule), which helps the agent understand the tool's behavior without needing parameter details.

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?

Clearly identifies the tool as listing authenticated user's saved searches with their filters and alert schedule. Distinguishes from sibling tools like save_search (create) and delete_saved_search (delete) by focusing on the list action.

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 when to use (when wanting to list own saved searches) but lacks explicit guidance on when not to use or alternatives. Provides authentication requirement but no exclusions.

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

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

With no annotations, the description covers the tool's behavior well: it enriches with AI, gathers market data, transitions to Active, returns a pipeline ID, and fails with readiness checks. It does not mention potential side effects or idempotency, but overall transparent.

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 concise with three sentences, each conveying key information. It is front-loaded with the main action ('Kick off the publish pipeline') and contains no redundant text.

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 the tool's complexity (AI enrichment, market data, transition, readiness checks) and lack of output schema, the description provides sufficient detail about the pipeline process and failure conditions. It could include more on the return format, but the pipeline ID expectation is clear.

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 does not add new meaning beyond the schema's description of 'hashid' as the listing identifier. No additional constraints or formats are provided.

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 clearly states the tool kicks off the publish pipeline for a draft listing, specifying the actions (enriches with AI, gathers market data, transitions to Active) and distinguishes it from sibling tools like create-listing-tool and update-listing-tool.

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 indicates the tool is for publishing draft listings and notes it fails with a readiness checklist, providing context. However, it lacks explicit guidance on when not to use it or alternatives, though siblings like get_pipeline_status are implied for progress tracking.

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?

Description discloses email digest behavior and authentication need, but with empty annotations, it carries full burden. Does not state side effects like overwriting existing saved searches with the same name, or the scope of the 'current search' (e.g., from a prior search_listings call).

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, efficient and front-loaded with key information (save, alerts, authentication). However, some detail is sacrificed for brevity.

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 the tool is a mutation with no output schema and 3 optional parameters, the description lacks critical context about the effect of parameters, return value (e.g., confirmation or ID), and error handling. Incomplete for an agent to use reliably.

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% (all 3 parameters described in schema). The description adds no additional meaning beyond what schema provides. 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?

The description clearly states the tool saves a search as a named alert and mentions email digests. It distinguishes from sibling tools like delete_saved_search and list_my_saved_searches, but does not explicitly specify what 'current search' refers to.

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 mentions 'Requires authentication.' Provides no guidance on when to use this tool versus alternatives like search_listings or interpret_search. Missing context about prerequisites or scenarios.

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?

Describes behavior: paginated hits and facet counts. No annotations present, so description carries full burden. Lacks details on rate limits or auth, but sufficient for a read-only search tool.

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 concise sentences. First states purpose and output, second gives usage guideline. No unnecessary words.

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?

Covers purpose, output (paginated hits with facets), and usage context. No output schema, but high-level return description is adequate. Missing details on error cases or advanced pagination, but acceptable given simplicity.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning for filters (Typesense field names, ranges, multi-select, booleans) and query (free-text examples). Refers to get_registry for valid values.

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?

Clearly states the verb 'Search' and resource 'commercial real estate listings'. Returns paginated hits with facet counts. Differentiates from sibling tools like interpret_search by indicating workflow.

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 advises to call interpret_search first for AI-driven search, providing clear usage context. Implies direct use for non-AI searches.

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

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

With no annotations, the description covers key behaviors: only writable fields accepted, enum handling (single/array), clearing with null, rejection with guidance for computed fields, and returns the full updated listing. It lacks details on authorization beyond 'listing you own' but is otherwise transparent.

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 paragraph with no wasted words. It front-loads the core purpose, then efficiently covers parameter details, constraints, and return behavior. Every sentence adds value.

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 the tool has 2 parameters and no output schema, the description sufficiently explains the return (full updated listing) and error handling (rejection with guidance). It is complete for the complexity level, though some details like idempotency or rate limits are omitted.

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% with descriptions for both parameters. The description adds significant meaning beyond the schema: includes an example of the attributes map, explains enum and multiselect handling, and clarifies the clearing mechanism (null). This elevates it above 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?

The description clearly states the action: 'Set broker-authored attributes on a listing you own.' It uses a specific verb ('Set') and resource ('listing'), and distinguishes from siblings by explicitly mentioning that hot columns require update_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?

The description explicitly tells when to use this tool versus update_listing for certain fields, and implies that only writable fields from get_registry are acceptable. This provides clear context for tool selection.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It states that the tool returns 'the full updated listing exactly as stored,' which is useful for understanding the response. It implies mutation but doesn't mention permissions or side effects. The added info is valuable beyond the schema.

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

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

The description is extremely concise: two sentences. The first sentence states purpose and constraint, the second describes the return value. No redundant information. Every word 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?

Given the tool has 4 parameters, no output schema, and empty annotations, the description is fairly complete. It covers purpose, parameter usage constraint, and return behavior. It could be improved by explicitly stating error conditions (e.g., if multiple groups are passed), but overall it provides sufficient context.

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% with descriptions for each parameter. The description adds the crucial constraint that only one of the three optional groups should be passed, which is not in the schema. This enhances the agent's understanding of parameter usage and valid combinations.

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 clearly states the verb 'update', the resource 'listing', and the specific aspects: parcel, pricing, or marketing data. It also explicitly distinguishes from sibling tools by specifying exactly which data groups can be updated, providing clear 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?

The description provides actionable guidance: 'Pass exactly one group (parcel, pricing, or marketing).' This tells the agent which parameters to use and how to select among them. However, it does not explicitly discuss when not to use this tool or mention alternatives for other updates (e.g., status changes), which are provided among sibling tools.

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

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

With no annotations, the description correctly highlights the irreversible nature (terminal status). It could mention side effects like removal from searches, but the key behavioral trait is well covered.

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 no fluff. Every sentence adds necessary 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?

The tool is simple with one parameter and no output schema. The description covers the essential behavioral and usage aspects, though it could mention prerequisites or response format.

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 no extra meaning about the 'hashid' parameter beyond the schema's description.

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

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

The description clearly states 'Withdraw a listing, removing it from public search.' This is a specific verb+resource that distinguishes from sibling tools like update-listing or publish-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?

It explicitly says 'This is a terminal status — the listing cannot be re-activated; create a new listing instead.' This tells the agent when to use (withdraw) and when not to (if re-activation needed), with a clear alternative.

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