castles

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

Without annotations, the description discloses key behaviors: results are sorted by distance, include 'distance_km', and the radius defaults/max are specified. It doesn't mention idempotency or side effects, but the listing nature implies read-only 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 concise sentences with essential information front-loaded. No filler or 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?

Given no output schema, the description adequately describes the output format (distance_km, sorted). It mentions the default/max radius and provides usage guidance. Minor omission: no mention of the 'limit' parameter's default behavior.

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 40% (limit and radius_km have descriptions; latitude, longitude, category do not). The description adds radius defaults but does not clarify the missing parameters. It provides 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?

The description specifies the verb 'List' and the resource 'landmarks within a radius of a WGS84 coordinate', and clarifies the ordering ('nearest first'). It provides a concrete usage example ('For "castles near <place>"...'), which distinguishes the tool from siblings like 'search_castles' that likely use text-based queries.

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

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

The description gives explicit instructions for the common use case ('geocode the place yourself, then call this'), which aids selection. While it doesn't explicitly state when not to use this tool, the guidance is clear and actionable.

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, but description strongly implies a read-only fetch. Could explicitly state non-destructive nature, but the verb 'Fetch' and the output description make it clear.

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 key information, no filler, includes conditional guidance. 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?

For a single-parameter, no-output-schema tool, the description lists all return fields, explains identification methods, and links to a sibling tool. Complete for effective use.

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 covers the single parameter with full description; description merely repeats what the schema says, adding no new semantic information. 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?

Clearly states it fetches a single castle's full record by slug or exact name, listing the returned data fields. No tautology; distinguishes from sibling tools like search_castles.

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 search_castles first if slug is uncertain, providing clear when-to-use guidance and an alternative.

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, so description carries full burden. It says 'computed live from the atlas' indicating real-time computation. It lists what statistics are included but doesn't specify performance or whether it's read-only. Still, it gives adequate behavioral context for a stateless read 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 that are front-loaded with the main purpose and include specific examples. No wasted 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?

Given no output schema, the description lists the categories of statistics (totals, top countries, etc.) and references a full write-up URL. It could detail the response format more, but for a simple stats tool it's fairly 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?

There are no parameters, so the description provides all necessary semantic meaning by detailing what statistics the tool returns.

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 provides headline statistics computed live from the atlas, listing specific categories like totals by type, top countries, etc. It distinguishes itself from sibling tools by focusing on aggregate data rather than individual castles or searches.

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 it's 'the source for claims like which country has the most castles', giving clear usage context. It does not explicitly state when not to use, but the alternative tools (get_castle, top_castles) are implied.

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 the return format (country name and ISO code), ordering (most first), and provides a navigation URL for country pages. It does not mention any side effects or limitations, but for a read-only list tool, this 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?

The description is two sentences, front-loaded with the core purpose and ordering, followed by return details and URL. Every phrase adds value with no redundancy or 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?

Given the simple nature of the tool (no parameters, no output schema), the description fully discloses what is returned and how to access country pages. It is complete for the expected use case without missing information.

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 has zero parameters, so the baseline is 4. The description correctly does not attempt to explain parameters, and the empty schema already reflects the lack of inputs.

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 lists every country in the atlas with its landmark count, ordered most first, and explicitly answers the question 'which country has the most castles.' This distinguishes it from sibling castle-focused tools like get_castle or search_castles.

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

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

The description gives a clear use case: 'answers which country has the most castles.' It implies when to use this tool for country-level comparisons, but does not explicitly mention alternatives or exclusions, so it falls 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?

With no annotations, description discloses key behaviors: returns one random record, optional country filter. Adequate for a simple read 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?

Single sentence front-loads purpose and is perfectly concise 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?

Given the tool's simplicity (one optional param, no output schema), the description covers return type, optionality, and intended use completely.

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 parameter description already explains 'country' as optional. Tool description adds context ('optionally limited to a country') but minimal extra value.

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 returns one random landmark with full record, optionally filtered by country. It distinguishes from siblings like get_castle (specific) and castles_near (proximity).

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 mentions use cases like discovery, quizzes, and 'castle of the day'. Implies when not to use via sibling tool names but lacks explicit exclusions or alternatives.

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 fully carries the behavioral burden. It discloses the matching behavior (accent- and case-insensitive substring), the ordering (best-match-first, then by fame), the result fields (coordinates, founding century, fame rank, atlas/Wikipedia links), and the retry fallback. This gives an agent a complete picture of what to expect.

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?

Every sentence earns its place: the first defines the collection and matching, the second details filters and result ordering, the third gives a search tip. It is front-loaded, compact, and free of 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?

Even without an output schema, the description enumerates the return fields (coordinates, century, fame rank, links) and describes ordering, filters, and fallback behavior. Given the 100% schema coverage and the simplicity of the search use case, the description is fully sufficient for an agent to select and invoke the tool 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?

The schema already covers all four parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantics: 'accent- and case-insensitive substring match' for query, 'name or ISO code' for country, and the category enum is echoed. It does not discuss limit, but the schema already documents that; the description enriches the core matching 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?

The description uses a specific verb ('Search'), names the resource ('the atlas’s 6,412 castles, fortresses, palaces and ruins'), and scopes it by matching ('by name'). It clearly distinguishes from sibling tools like castles_near or get_castle by focusing on name-based search rather than location or specific 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?

The description clearly implies when to use the tool ('by name') and provides practical guidance on query refinement ('If nothing matches, retry with a shorter fragment of the name'). It also explains optional filters for country and category. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous enough.

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 explains the ordering mechanism (fame rank, a blend of Wikipedia coverage and readership), provides a concrete example (rank 1 = Numantia), and notes filtering behavior. It does not describe output shape or pagination, but these are less critical for a read-only ranking list.

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 main purpose, followed by a concise explanation of the ranking and a usage hint. Every sentence earns its place, and the structure is easy to scan.

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 listing tool with no annotations, output schema, or nested objects, the description covers the essential aspects: purpose, ranking basis, worldwide vs. country scope, and filtering options. It is nearly complete; only explicit alternative-tool references are missing, though sibling names are available in 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 description coverage is 67%, covering limit and country. The description adds that country/category filtering can be combined and clarifies worldwide scope, but the category parameter is only self-documented via its enum and limit default is already in the schema. This is adequate but not a major enhancement over the schema.

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

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

The description clearly states what the tool does: returns the most famous landmarks ordered by Castlemap fame rank, with optional country/category filtering. It also distinguishes itself from siblings by positioning itself as 'the direct answer to most famous castles in <country>', which is specific and actionable.

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 clear usage context: use for famous landmarks worldwide or in a country, with optional filtering by country and/or category. However, it does not explicitly mention when not to use this tool or name alternative siblings, so it stops short of full guidance.

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