Mind the Gates — UK level crossings

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

No annotations are provided, so the description carries the full burden. It reveals the ranking is based on 'predicted' road-closed time, hinting at a model or forecast. However, it does not disclose whether the data is real-time, cached, or requires authentication, nor does it explain the prediction methodology or limitations.

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, clear sentence with no unnecessary words. It is front-loaded with the tool's primary purpose and is perfectly 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?

The tool has no parameters or output schema, so the description must convey the output format. It states 'ranking of crossings' but does not specify whether the output is a list of crossing IDs, names, or objects with times. For a simple read operation, this is moderately complete but leaves ambiguity.

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 schema provides no additional meaning. The description adds value by specifying the ranking criterion ('by predicted road-closed time'), which is not evident from the schema. This justifies a score above the baseline of 4.

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 provides a ranking of crossings by predicted road-closed time for today. The verb 'ranking' implies a list, and the resource 'crossings' is specified. It distinguishes from siblings like crossings_near (location-based) and crossing_status (status of a specific crossing).

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 explicit when-to-use or when-not-to-use guidance is given. The description does not mention alternatives or context. For a simple tool with no parameters, usage is arguably implicit, but the lack of any guidance is a gap.

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 are provided, so the description must bear the full burden of behavioral disclosure. It does not specify behavior such as handling of invalid coordinates, empty results, output format, or parameter constraints beyond the schema. The description is too minimal to be 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 sentence, making it concise. However, it lacks detail that could be included without verbosity. For a tool with three parameters, more structured information would be beneficial. It is not overly long, but it is under-specified.

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 and lack of annotations or output schema, the description should provide more context, such as return format, error handling, and parameter roles. The current description leaves the agent to infer too much, making it incomplete.

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 0%, and the description adds no information about parameters. It does not explain that 'lat' and 'lon' are in decimal degrees or that 'limit' controls the maximum number of results. The description fails to add meaning 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 clearly states the tool finds nearest listed level crossings to a lat/lon. It uses a specific verb ('nearest') and identifies the resource ('level crossings') with input coordinates. This effectively distinguishes it from siblings like 'busiest_today' (busiest crossings) and 'list_crossings' (all crossings).

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 is provided on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions. The description only states what the tool does, not when it is appropriate.

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 are provided, so the description must carry the full burden. It mentions 'live' status and markdown output, but does not disclose behavioral traits such as rate limits, caching, or error handling. The description is adequate but not rich.

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: one for output content and format, one for parameter usage. No redundant words, 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?

For a simple tool with one parameter and full schema coverage, the description is complete enough. It explains what the tool returns and how to call it, though missing details on what happens if the crossing is not found.

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 covers the single parameter with a clear example. The description adds value by explaining the source of the value ('from list_crossings') and reinforces acceptable inputs, going 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 the tool returns live barrier status, closure timeline, and approaching trains for a single crossing. It specifies the output format is markdown, and distinguishes from siblings by focusing on one crossing vs. lists.

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 instructs to pass the crossing's URL word (from list_crossings) or its name, providing clear context. However, it does not explicitly state when not to use this tool or contrast with siblings like busiest_today.

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 must fully convey behavioral traits. It states it returns matches with status URLs, but omits whether the operation is read-only, requires authentication, has rate limits, or paginates results. For a read/search tool, this is insufficient.

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 concise sentence covering purpose, search criteria, and output. It is front-loaded and wastes no 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?

For a simple tool with two parameters and no output schema, the description covers key aspects: search criteria and return content (status URLs). However, it does not detail limit behavior or error cases, which would improve completeness.

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 50% (only query described). The description adds context for query ('name, URL word or region'), partially compensating. However, the limit parameter has no description in schema or description, leaving its purpose (max results) unclear.

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 searches for UK level crossings by name, URL word, or region, and returns matches with status URLs. This differentiates it from sibling tools like crossings_near (location-based) and crossing_status (status lookup).

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 searching by textual identifiers (name, URL word, region), but lacks explicit guidance on when not to use it versus alternatives. No direct mention of when to prefer other sibling tools.

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