education-data

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

Annotations already declare readOnlyHint=true, so the description adds no behavioral context; it neither contradicts nor enriches transparency.

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 focused sentence with no redundancy, front-loading the purpose effectively.

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 2 parameters and no output schema, the description is adequate but lacks usage guidance and parameter elaboration, leaving gaps.

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 only 50% (lang described, query not), and the description does not elaborate on parameter meanings beyond what the schema provides.

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 BrightKey's cited answers for international-education questions and returns best-match sourced answers, distinguishing it from sibling tools like compare_universities or general search.

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 the tool is for common questions with cited answers but does not explicitly state when to avoid it or mention alternatives among siblings.

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 indicate readOnlyHint=true, so destructive behavior is not expected. The description adds valuable context by detailing the output: 'per-dimension tier deltas + a sourced tier-delta paragraph' and emphasizing 'tiers, not a single rank', which clarifies the return format beyond the annotations.

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, each serving a purpose: the first states the action, the second specifies the output format. No extraneous words or repetition; it is efficiently structured.

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 description covers the core functionality and output format. It does not list the 6 dimensions (likely domain knowledge) or error conditions, but given the tool's simplicity and the presence of annotations, it provides sufficient context for an agent to select and invoke the tool appropriately.

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 input schema has low description coverage (33%, only 'lang' described). The description compensates by explicitly stating that parameters 'a' and 'b' are universities, adding meaning that the schema (just 'string') lacks. This clarifies parameter semantics despite the schema gap.

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 verb 'compare' and the resource 'universities', and specifies it uses 'BrightKey's 6 dimensions'. It distinguishes itself from siblings like 'get_university_profile' (single university) and 'list_universities' (listing), making its purpose unambiguous.

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 comparing two universities on specific dimensions, but does not explicitly state when to use versus alternatives like 'match_schools' or 'degree_roi'. No exclusions or when-not guidance is provided, leaving the agent to infer context.

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 indicate readOnlyHint=true, and the description adds useful behavioral context: it returns numeric ROI data and break-even year, and accepts scope-limited slugs. No contradictions with annotations.

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 with zero waste. The first sentence states the core purpose, and the second explains the input format. Front-loaded and 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?

Given the tool's simplicity (2 params, no output schema, no nested objects), the description fully covers what the tool returns and how to invoke it. No gaps remain.

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%, but the description adds significant value by explaining that 'country' must be a preset slug and 'all' produces a ranked list, providing examples that the schema descriptions lack.

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 '5-year-after-graduation net ROI + break-even year' for a degree, with a specific verb and resource. It also explains the input as a preset country slug or 'all', making it distinct from sibling tools like compare_universities or get_university_profile.

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?

Excellent examples of valid inputs (germany, uk-oxbridge, us-private) and the special case 'all' for a ranked list. While it doesn't explicitly say when not to use this tool over siblings, the scope is clear enough for an AI agent to infer appropriate usage.

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 indicate readOnlyHint=true, so the description adds minimal behavioral depth. It correctly implies a read operation but offers no additional details like auth or rate limits.

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?

A single, front-loaded sentence with no extraneous words, efficiently conveying the tool's purpose and usage context.

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 description is adequate for a simple fetch tool, specifying it returns 'full content'. Without an output schema, more detail on the response structure would be beneficial, but it's not severely lacking.

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 description adds meaning for the `id` parameter by showing valid formats (uni:<slug>, etc.), which the schema lacks. For `lang`, the schema provides its own description, so the contribution is partial.

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 fetches full content for an ID, with specific format examples from search results. It distinguishes from sibling tools like search and list.

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 states 'for an id returned by search', providing usage context. However, it does not mention alternative approaches or when not to use 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 declare readOnlyHint=true, indicating safe read operation. The description adds no behavioral traits beyond that, though it mentions bilingual output. With annotations covering safety, a 3 is appropriate.

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, front-loaded sentence that conveys all essential information without verbosity.

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 parameters and no output schema, the description adequately covers what the tool does and returns (list of profile components, bilingual capability).

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 schema already documents both parameters (slug and lang). The description adds minimal extra meaning beyond what the schema provides, only referencing slug implicitly.

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 retrieves a detailed BrightKey profile for a single university by slug, listing specific contents like tier ratings, verdict, strengths/weaknesses, etc. This distinguishes it from siblings such as compare_universities and list_universities.

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 use when needing a full profile for one university, but does not explicitly state when not to use it or provide alternatives. However, sibling tool names give context.

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 indicate readOnlyHint=true. The description adds that the tool returns tiers and verdict, but does not disclose pagination, caching, or any constraints beyond the annotations.

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 listing output fields, efficient but lacks structure like parameter explanations or usage notes. Could be more informative without being verbose.

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?

No output schema but description covers return fields. Missing details on pagination, default limit, sorting, error handling, or rate limits, which are important for a list tool with optional filters.

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 0%, yet the description only mentions 'optional filters' without explaining each parameter's meaning, format, or constraints. For example, 'country' lacks validation hints, 'minTier' enum is clear but still not elaborated.

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 BrightKey-profiled universities with optional filters and specifies return fields (slug, name, country, city, tiers, verdict). It distinguishes from siblings like get_university_profile (single university) and search (general).

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 indicates optional filters for listing, implying use for filtered lists, but lacks explicit guidance on when to use alternatives like search or compare_universities. No exclusion criteria or prerequisites.

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=true and openWorldHint=false. The description adds that it returns specific fields but does not disclose pagination, rate limits, default limit, or ordering behavior. Some value added but not comprehensive.

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 well-structured sentence that front-loads the core action ('List'), then adds filters and return details. No unnecessary words, though could be slightly more structured with bullet points for return fields.

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 3 parameters, no output schema, and annotations, the description provides the major return fields and filter criteria. However, it omits default behavior, ordering, and result limits beyond what is in the schema. Moderately complete but leaves gaps.

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 only 33% (city example provided). The description provides curriculum examples (IB, A-Levels, AP) that are missing from the schema, and mentions return fields. However, the 'limit' parameter is not described, and city description is minimal. Partially compensates for low coverage.

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 BrightKey-profiled international schools with specific filter criteria (city, curriculum) and lists return fields (name, curricula, fees, inspection rating, tiers). It distinguishes from siblings like 'list_universities' by focusing on international schools.

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 use for finding international schools by city/curriculum, but does not explicitly state when to use this tool vs alternatives like 'search' or 'list_universities'. No exclusions or prerequisites are given.

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?

Adds value beyond annotations by specifying return format ({id, title, url}) and linking to fetch(). No contradiction with readOnlyHint=true. Could mention pagination or rate limits, but adequate for a read-only search.

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 action and resource, no redundant words. Every sentence serves a purpose.

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?

Minimal for a search tool with many siblings. Lacks details on result scope, pagination, or error handling. Returns a basic structure but doesn't fully compensate for the absent 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 0% with no description for the 'query' parameter. Description does not elaborate on format, examples, or constraints, leaving the agent without guidance on how to construct a valid query.

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 specific verb 'search' and resource 'universities, schools, and answers'. It distinguishes from sibling tools like 'fetch' by noting that search returns {id, title, url} and pass id to fetch() for details, which clarifies the tool's role.

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?

Implies when to use fetch() vs search. However, no explicit guidance on when to use search over other siblings like 'answer_education_question' or 'get_university_profile'. Context provided is useful but could be more precise.

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