HammerMap: Spanish court auctions and State sales

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

Annotations already declare read-only, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds behavioral context beyond that by disclosing data-freshness semantics (data_updated, latest_boe_publication, update_frequency) and confirming the call takes no arguments, though it says nothing about result size or whether counts can be stale.

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

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

Three short sentences with no filler; the facet inventory leads and the usage guidance follows. Slightly better front-loading would put the purpose before the field enumeration, and the parenthetical freshness list is dense but 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 an output schema present, the description does not need to explain return shapes, and annotations carry the safety profile. For a no-argument, read-only discovery tool, everything an agent needs to decide to call it is present.

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

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

There are zero parameters and the description explicitly confirms 'No arguments,' matching the empty schema with additionalProperties false. No further parameter meaning is needed.

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 names the specific resource (facet counts of current listings by type, procedure, asset type, province) and the extra data returned (price range, countries, freshness fields). It is instantly distinguishable from get_listing (single record) and search_listings (the consumer of these filter values).

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 states two use cases: discovering valid filter values for search_listings, and answering 'how many / how fresh' questions, which routes the agent away from the search siblings. It never states a when-not-to-use condition, but the positive routing is clear enough to act on.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered; the description adds genuinely new behavior: it errors when the id is no longer listed, exposes data freshness via attribution.data_updated, and flags the risk analysis as non-legal-advice. It omits auth/rate or pagination behavior, 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?

Front-loaded with the core action and keyed on the id, then a single long enumeration of returned fields. Dense but every clause maps to real content (lots, deposit, deadline, mode, place, risk analysis, links, freshness); the official-channel caveat at the end is short and useful.

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 an output schema present, return-value explanation is optional, yet the description still previews the payload, states the error condition, identifies the freshness field, and redirects bidding/payment to official urls. 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% and the pattern already constrains the id format, so the baseline is 3. The description adds meaning beyond the schema by decoding what the two id prefixes represent (court auctions vs State sales), helping the agent validate provenance.

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 (retrieve full record) and resource (one listing), scoped by id, and immediately distinguishes itself from the sibling search_listings by requiring an id that came from that search. The id prefix conventions (SUB-… court auctions, BOE-B-… State sales) further pin down the resource type.

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 frames the call as a follow-up to search_listings and gives the exact id forms it accepts, so an agent knows when this tool applies. It does not spell out an exclusion case (e.g. what to do instead when the id is unknown) beyond noting an error is returned.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, so safety is covered. The description adds genuinely useful behavioral context: Spain-only coverage, once-per-working-day refresh with attribution fields exposed, and the important caveat that BOE court-auction notices lack price, description and closing date. It could note more about pagination limits or result caps, but the missing-data caveat is exactly the kind of context annotations can't convey.

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

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

Front-loaded with purpose and usage, then returns, then caveats and freshness. It is dense but nearly every sentence carries information; the short-record field list overlaps slightly with the existing output schema, but that is minor.

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 16 optional parameters, an output schema and annotations present, the description supplies everything an agent still needs: coverage, freshness, the AND-combination rule, the price/deadline absence caveat and the get_listing handoff. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real semantic value beyond the schema by stating that all filters are optional, combine with AND, and that Spain-only coverage ties to the country parameter. That AND-combination rule is not obvious from 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?

States a specific verb and two precisely defined resources (BOE section IV court auctions and section V-B state sales) and explicitly distinguishes from get_listing by naming it as the follow-up for full records. An agent can tell exactly what this tool returns versus its siblings.

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

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

'Use it first to find listings by province, town, type, asset type, starting price or dates; then call get_listing with an id for the full record' gives an explicit ordering and the alternative tool. Nothing is left to inference about when to choose this versus get_listing.

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