Catchmently

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world behavior, so the description's job is to add context — which it does by disclosing the result cap (up to 10 matches), the returned identifiers for chaining into get_school, and the geographic scope (England). It does not cover truncation behavior when more than 10 match, which is the only remaining gap.

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 tightly packed sentences with no filler: the positive scope comes first, the negative constraint and routing come second. Every clause carries operational information, including the result cap and the ID chaining hint.

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 two-parameter lookup with no output schema, the description supplies everything an agent needs: what it searches, geographic scope, result limit, the shape of returned identifiers, and how to route to the correct alternative. 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, but the description adds real meaning beyond the schema by telling the agent that the area parameter does not accept council or borough names — a constraint not present in the schema text and one that would otherwise cause failed or empty searches. It also clarifies that 'name' is a partial match.

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 (find schools/nurseries/childcare providers by name) scoped to England, and explicitly separates itself from search_near_postcode for geographic 'near X' lookups. It also names the downstream sibling get_school, so an agent can distinguish it from the other four sibling tools without reading schemas.

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 both when-to-use (name-based lookup, optionally narrowed by town/county/postcode) and when-not-to-use, with a concrete counterexample: council or borough names like 'near Lambeth' should go to search_near_postcode. The alternative tool is named explicitly alongside the condition that selects 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?

Annotations already establish a read-only, idempotent, non-destructive operation. The description adds meaningful context beyond that: data is source-attributed, published by councils or schools, and free without sign-in until a specific date.

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 tight sentences, front-loaded with what is returned and followed by the access condition. There is no redundant wording.

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 only one parameter and no output schema, the description reasonably covers what comes back, including source attribution and catchment context. It does not explain result structure or how multiple entry years are organized, which would be helpful without an output schema.

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 school_id is fully documented with examples. The description reinforces that the lookup is for one school but does not add format or constraint details 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 resource and scope: every published last distance offered for one school, plus the council catchment or priority area. It clearly differs from area-level tools, though it does not explicitly name siblings such as get_area or get_school.

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?

Usage is implied by 'for one school' and the mention of entry year and intake, but there is no explicit when-to-use, when-not-to-use, or alternative comparison against get_school, get_area, or search_near_postcode.

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, so the safety profile needs no restating. The description adds genuinely useful context beyond them: response content is auth-dependent, with roughly a dozen datasets marked 'locked' for non-pass holders. It stops short of saying how locked fields are represented or what happens for an invalid or non-England postcode.

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?

It is a single sprawling sentence built from semicolon-separated catalogue lists, so the reader has to parse a data inventory before reaching the operationally important auth-gating clause. Because there is no output schema, enumerating return families earns some of its length, but the ordering buries the most decision-relevant fact near the end.

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 read tool with no output schema, the description is substantially complete: it covers coverage area, granularity, the full data inventory, and the auth-dependent subset. The remaining gap is edge-case behavior on rejected postcodes and the representation of locked values, both of which an agent would need to interpret a response.

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?

Only one parameter exists and schema coverage is 100%, so the schema already carries maxLength and the 'Full England postcode, e.g. SE22 8DL' example. The description's 'one full England postcode' reinforces the fullness and country constraint but adds no format or validation detail the schema lacks, which is the baseline 3 case.

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 states a specific verb and resource: area facts for 'one full England postcode', with a concrete enumeration of the fact families returned. It is clearly distinguishable in scope from school-oriented siblings, though it never names search_near_postcode as the nearby-area alternative, so differentiation is achieved by implication only.

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?

Usage constraints are embedded rather than stated as guidance: 'one full England postcode' implies no partial outcodes and no Scotland/Wales/NI coverage, and the pass/locked sentence implies results degrade for anonymous callers. There is no explicit when-to-use versus when-not-to-use statement and no reference to any sibling tool.

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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the last-distance-offered and catchment/priority-area fields are only present for a signed-in pass holder, and the postcode parameter changes the result shape. It says nothing about behaviour for an unknown or malformed ID, which is the remaining gap.

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 sentences, front-loaded with the resource and ID, then the payload, then the conditional extras and the postcode modifier. Dense but every clause carries information; the '(see get_admission_distances)' cross-reference is compact routing rather than 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?

With no output schema the description must carry the return-value burden, and it does by listing the data sections, including the auth-gated ones. For a 2-parameter read tool with full annotation coverage this is close to complete; only error/not-found behaviour and response shape granularity are absent.

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, but the description earns an extra point by telling the agent where school_id comes from (find_school or search_near_postcode) — provenance the schema's 'Catchmently ID, e.g. gias:138342' does not convey. The postcode explanation merely restates the schema's 'straight-line distance' wording, so it adds little.

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?

Names a specific resource and scope ('Details for one school or nursery by Catchmently ID') and enumerates exactly what comes back: register details, latest Ofsted outcome with quoted strengths and areas to improve, exam results, applications and offers. Even without the sibling list an agent could tell this apart from a search or distance 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?

It routes the agent on ID provenance ('from find_school or search_near_postcode') and points to get_admission_distances for the fuller distance data, plus states that supplying a postcode adds a straight-line distance. What's missing is an explicit exclusion, e.g. that this is not for finding a school when you only have a name or postcode.

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 this a safe, idempotent, closed-world read, so the bar is lower. The description still adds real behavior beyond them: results are ordered by straight-line distance from the postcode centre, each record carries Ofsted outcome, selective status and religious character, and — importantly — the last-distance-offered figure is gated to signed-in pass holders, which an agent must know to interpret partial results.

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?

Purpose and ordering are front-loaded in the first sentence, with the return-shape and gating detail following. It is dense but each clause carries information; the second sentence is long and could be split for readability without losing content.

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 no output schema, the description must characterize results, and it does: it names ordering, distance metric, the per-school attributes, and the paywall constraint on the distance figure. It stops short of describing result envelope details (count, paging beyond limit, behavior when nothing is in radius), which is a minor remaining gap.

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 high (86%), so the baseline is 3. The description nevertheless adds meaning: distance is measured as straight-line from the postcode centre (clarifying radius_miles), postcode accepts a district such as SE22, and published_distance_only corresponds to 'whether a last distance offered has been published' — reinforcing what the returned flags mean.

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 schools, nurseries and childcare') plus scope ('near an England postcode') and ordering ('nearest first, by straight-line distance'). This is clearly distinguishable from a name lookup like find_school or a single-record get_school; an agent can route on the geographic-search framing alone.

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?

Usage is implied rather than stated: the postcode-accepting scope signals when the tool applies, and radius_miles/published_distance_only hint at narrowing use. However, no sibling is named and no when-not condition (e.g., use find_school for name lookup, get_school for a single known school) is provided, leaving the agent to infer tool selection.

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