ScareMap

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds value beyond them by scoping the counts to public haunts only and confirming the tool takes no input.

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 what the tool returns, then when to call it and the no-input fact. Nothing is padded or repeated from the 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?

With an output schema present, an input-free schema, and full annotations, the description covers everything an agent needs: contents of each row, the routing trigger, and the absence of arguments.

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

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

There are zero parameters, so the baseline is 4; the description reinforces this with 'Takes no input', removing any doubt that arguments are expected.

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 (list haunt categories) plus exactly what each entry contains (display label, count of public haunts). It is trivially distinguishable from the haunt-lookup siblings scaremap_find_haunts / scaremap_get_haunt.

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 call-first condition ('when the user asks what kinds of places ScareMap covers') and a second concrete trigger (to obtain valid values for the category filter used by the other tools). No alternatives are needed since no sibling overlaps this purpose.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds behavior annotations don't: nearest-first result ordering and the important caveat that unrated haunts (review_count 0) have null ratings and are dropped when min_stars or min_scare is set. It doesn't discuss pagination or result caps beyond limit.

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 core action and ordering, then prerequisites, then caveats, then sibling routing, in four dense sentences with no filler. Every sentence carries information an agent needs to select or invoke the tool correctly.

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?

An output schema exists, so return values need not be explained. For an 8-parameter geo-search tool the description covers the required lat/lng prerequisite, the geocoding gap it cannot fill, the filter semantics including the null-rating edge case, and sibling routing — 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 description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the null-rating/unrated interaction with min_stars and min_scare, and the filter axes (category, season, minimum visitor ratings). It does not explain the distinction between min_scare and min_stars beyond the schema's own wording.

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 set ('Find haunted houses, haunt farms, ghost tours, horror escape rooms and haunted places') scoped by radius around lat/lng, and adds the ordering guarantee 'nearest first'. It explicitly differentiates from siblings by naming when to use scaremap_find_haunts_in_city and scaremap_get_haunt instead.

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

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

Gives an explicit trigger ('when the user gives a place, address or coordinates and wants scary things to do nearby'), a prerequisite ('Geocode a place name to lat/lng first'), and an exclusion ('this tool does not search by name'). It also routes to two named alternative tools with the conditions that select them.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. Beyond that the description discloses result ordering (review count, then name) and failure behavior (city-not-found errors enumerate the state's known cities), which are genuinely useful traits not present in 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?

Front-loaded with purpose and scope, then usage condition, then input/ordering/error details and the alternative. Every sentence carries information; no filler or repetition.

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 annotations covering safety, a 100%-covered schema, an output schema, and no nesting, the description supplies exactly the remaining pieces an agent needs: trigger condition, ordering, error fallback and the sibling to use instead.

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 examples for state/slug/code, limit bounds and category enum already documented, so the 3 baseline applies. The description's note that state accepts name, slug or two-letter code largely restates the schema, adding little beyond the city-error behavior.

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

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

States a specific verb (List) plus resource (haunts) and the precise scope (a US state, or one city within it), explicitly contrasting with the point-distance search done by scaremap_find_haunts. An agent can distinguish it from all three siblings 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?

Explicit trigger: 'Call this when the user names a state or city ... and has no coordinates', and an explicit alternative for the opposite case (scaremap_find_haunts for distance search). The category enum also points to scaremap_categories for the valid list.

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 read-only, idempotent, non-destructive, and closed-world traits, so the bar is lower. The description still adds real behavioral context: reviews are capped at 20 newest, reviews are anonymous, and a haunt with no reviews returns an empty list rather than erroring. It does not mention failure behavior for a bad slug/id.

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 tight sentences: return contents first, then usage trigger, then input sourcing, then edge-case behavior. Nothing is redundant and the most decision-relevant information is front-loaded.

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

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

An output schema exists, so return values need not be explained, yet the description still previews the payload and the 20-review cap. Combined with full annotation coverage and a fully described 2-param schema, an agent has everything needed to call this 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% and both parameters are documented in-schema, so the baseline is 3. The description only adds that either the slug or the haunt id may be passed and that the slug originates from sibling tool results, which is marginal value 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 (Get) and resource (one haunt) plus the exact fields returned: description, category, season, location, average ratings, and newest reviews. This clearly separates it from the sibling find/list tools, which return multiple haunts rather than a single full record.

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 says to call it 'after scaremap_find_haunts or scaremap_find_haunts_in_city when the user wants detail on a specific result,' naming both alternatives and the condition that selects this tool. It also tells the agent where the required input comes from ('Pass the slug from those results').

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