EduAtlas

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

Beyond the read-only/idempotent annotations, it discloses the result cap (25), what each result carries, and — most usefully — the exact exclusion logic: only place, phase, role level and a clearly different subject in the title will drop a job, so results must be re-read against the full CV. That approximate-matching caveat is behaviour an agent could not infer from annotations or schema.

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 purpose then input discipline then output/matching caveats — a sensible order. The enumeration of returned fields (school, place, pay, closing date, link) partly restates what the output schema already covers and could be trimmed.

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 15 optional parameters, an output schema and full annotations, the description covers the gaps that matter: input provenance, the 25-result cap and the loose matching semantics. It leaves edge cases such as sector defaults or the min_salary/salary_currency pairing to the schema, which documents them adequately.

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 already 93%, so the baseline is 3. The description adds real value by specifying the provenance of input values — draw only from the CV or conversation, use profile fields rather than raw CV text — which governs how every parameter should be populated, not just what it means.

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?

"Live school vacancies ranked for one teacher's profile" gives a specific resource and a ranking behaviour, and the quoted user question ("here is my CV, what is live now that fits me?") makes the profile-driven nature unmistakable. It does not name the siblings (search_teaching_jobs, schools_hiring), so the contrast with keyword search is implied rather than stated.

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 when-to-use case is framed concretely as a CV-in-hand, what-fits-me-now query, and there is an explicit negative instruction about what not to send (CV text, names, contact details). It stops short of naming an alternative tool or saying when a sibling search would be the better choice.

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 as a read-only, idempotent, non-destructive lookup. The description adds useful context: the record is public, includes a live vacancy count, and same-name schools are listed rather than silently resolved.

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 front-loaded with the resource and its scope, then moves to identification rules. The field enumeration is somewhat redundant with the output schema, but it remains efficient and useful for tool selection.

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 rich annotations and an output schema, the description covers what an agent needs: what the record contains, how to identify a school, how to disambiguate duplicates, and where slugs come from. Nothing material is missing for correct invocation.

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 value by explaining that the slug can come from a job result or an EduAtlas URL, and by stating the slug-or-name-plus-country identification rule despite no required parameters.

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: 'The public record for one school on EduAtlas.' It enumerates the record's contents and its identification methods, making it unmistakably distinct from the job-search 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?

It clearly explains how to identify the school, preferring slug from a job result or URL, otherwise name plus country with an optional town. It does not explicitly name alternatives or state when not to use this tool, but the usage context is clear.

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 non-open-world, so the safety profile is covered. The description adds one genuinely new behavioral fact — results are ranked by number of live vacancies and reflect current postings — but says nothing about pagination, result-set size caps, or what happens when a country has no data.

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 the scope front-loaded and the example question doing useful disambiguation work. The parenthetical qualifier list is slightly awkward and partly redundant with the schema's role description.

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 needn't explain return values, and annotations cover safety. The remaining gap is the undocumented limit parameter and no statement of how many schools a typical response contains, which matters for a ranked aggregation tool.

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 75%, so country, city and role are already documented in the schema, and the description only restates their meaning. The limit parameter (1–25) is undocumented in both schema and description, leaving the result-size control opaque.

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 — which schools are hiring in a country, ranked by live vacancy count — and names the output fields (school names, counts, page URLs). It implicitly separates itself from job-level siblings like search_teaching_jobs, but never names an alternative explicitly.

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 natural-language example ("which schools in Leeds are recruiting science teachers") gives a concrete usage context, and the optional city/role qualifiers are framed as refinements. It stops short of saying when NOT to use it, e.g. when the agent wants individual job listings rather than school aggregates.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful behavioral context beyond them: result cap of 20 per search, the fields returned (school, location, salary where published, closing date, job URL), the geographic coverage, and the non-obvious keyword semantics of "IB".

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 core action and coverage, then query examples, then return summary. Every sentence carries weight, though the "up to 20 jobs" detail mildly restates the schema's "20 per page" note.

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 return-value explanation is bonus rather than a requirement, and the description still summarizes it usefully. Combined with full schema coverage and annotations, an agent has nearly everything needed; only sibling differentiation and pagination/end-of-results behavior are 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 all four parameters are already documented, including the city/country/page semantics and the "IB" keyword. The description's example queries illustrate how subject, role and place words combine, but it adds no format or constraint detail the schema does not already carry.

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 ("Search live school vacancies on EduAtlas") and defines scope: teaching and leadership posts plus marked support roles across UK, Ireland and international schools. It is clear about what it searches, but it never contrasts itself with siblings such as find_jobs_for_me or schools_hiring, so the agent must infer the distinction.

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 effectively coaches query formulation with concrete examples ("physics teacher London", "IB maths Dubai", "SENCO") and explains the special "IB" filter, which is genuine usage guidance. However, it gives no guidance on when to pick this tool over find_jobs_for_me or schools_hiring, so tool-selection logic is left implicit.

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