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

Annotations already indicate readOnlyHint=true, so the description adds moderate value by specifying the scope of data returned (profile, topics, institutions), but does not contradict 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, concise sentence that conveys the tool's purpose with no unnecessary words, earning high marks for efficiency.

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 presence of an output schema, a single well-documented parameter, and a readOnlyHint annotation, the description fully covers the necessary context for an agent to understand the tool's behavior and return value.

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% for the single parameter, so the baseline is 3. The description does not add significant meaning beyond the schema's own description of accepted ID formats.

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 ('Fetch') and the resource ('full author profile'), specifying that it includes topics and institutions, which distinguishes it from sibling tools like fetch_institution or fetch_work.

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 such as get_author_works or search_authors. The description lacks context for selection.

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?

The description adds the term 'full' implying complete data, but does not detail what fields are returned or any side effects. Annotations already declare readOnlyHint=true, so the description provides minimal extra behavioral context. It is adequate but not enriched beyond the structured 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?

The description is a single, concise sentence that conveys the purpose efficiently. There is no redundant information, and every word is meaningful.

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 parameter, output schema present, read-only annotation), the description is minimally sufficient. However, it lacks details on error handling (e.g., what happens if the ID is invalid) and does not mention the output structure, relying solely on the output schema. This is adequate but not fully comprehensive.

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 covers the single parameter 'institution_id' with a description indicating acceptable ID formats (OpenAlex, ROR, MAG, Wikidata). With 100% schema coverage, the description adds no further meaning. Baseline score of 3 is appropriate.

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 'Fetch full institution profile', which uses a specific verb ('fetch') and identifies the resource ('institution profile'). This distinguishes it from siblings like 'fetch_author' and 'fetch_work', which operate on different resources.

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 provides no guidance on when to use this tool versus alternatives. For example, it doesn't mention that 'fetch_institution' is for retrieving a known institution by ID, while 'search_institutions' is for finding institutions by query. The agent is left to infer usage from 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 behavioral context by specifying the optional fulltext and prompt parameters, which allow retrieving PDF as markdown or an LLM summary, beyond the basic metadata fetch.

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-loading the core purpose. Every clause provides essential information without redundancy, making it easy for an agent to quickly understand the tool's capabilities.

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 4 parameters, existing output schema, and annotations, the description covers the main operation and key optional behaviors. It omits detailing 'include_abstract' but the default and schema provide context. Overall, it is sufficiently complete for a retrieval tool with good structured support.

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%, with 3 of 4 parameters described. The description adds meaning for 'fulltext' and 'prompt' by explaining their effects (PDF as markdown, LLM summary). It does not mention 'include_abstract', but the schema default and tool logic imply it, so the description adds 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 clearly states 'Fetch complete metadata for one work' with a specific verb and resource. It also distinguishes from siblings by mentioning optional PDF retrieval or LLM summary, which are unique to this tool compared to 'fetch_author' or 'search_works'.

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 does not explicitly state when to use this tool versus alternatives like 'search_works' or 'semantic_search_works'. There is no guidance on when not to use it, leaving the agent to infer from sibling names.

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, making the tool's read-only nature clear. The description adds no behavioral traits beyond listing works, so no additional value but no contradiction.

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 with no wasted words, efficiently conveying the tool's purpose with minimal fluff.

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 4 parameters and an output schema, the description is too sparse. It omits pagination, sorting behavior, and return format, leaving the agent to rely solely on 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 description coverage is 50% (author_id and sort have descriptions), but the tool description adds no parameter details. Limit and page lack documentation in both schema and 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 'List all works by a given author' uses a specific verb and resource, clearly distinguishing it from siblings like fetch_work (single work) or search_works (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 you need an author_id, and the parameter description hints to use search_authors, but no explicit when-to-use or alternatives vs other tools like search_works.

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 info beyond the fact that it searches. No contradictions.

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, no wasted words. Could be slightly more informative without losing conciseness.

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 6 parameters and high complexity, description is too minimal. Does not mention pagination, sorting, or other filters. Even with output schema, more details about search capabilities are needed.

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?

Description adds general context for the search (by name, by institution), but schema already covers parameter descriptions for 50% of parameters. Does not detail other parameters like limit, page, sort.

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 the verb (search), resource (author profiles), and optional filter (institution). Distinguishes from siblings like fetch_author and search_institutions.

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 when to use (search by name with optional institution filter), but does not mention when not to use or provide alternatives. Context from sibling tools helps but is not in the description.

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, so the tool is known to be a safe read operation. The description adds that it searches by name with filters, which is consistent but does not disclose additional behaviors beyond what annotations and schema provide.

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 that front-loads the core action. However, it omits important context about pagination and sorting, making it slightly under-specified for the number of parameters.

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 does not need to explain return values. However, despite covering the main search function and filters, it does not mention pagination, sorting, or the list nature of results, leaving gaps for a tool with 6 parameters.

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%, but the description does not add meaning beyond the schema for the documented parameters (query_string, country_code, institution_type). It fails to compensate for the undocumented parameters 'limit', 'page', and 'sort', which are not mentioned in the 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 verb 'search', the resource 'institutions', and the primary parameter 'by name'. It distinguishes from sibling tools like 'fetch_institution' (which likely fetches by ID) and other search tools for different resources.

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 institutions by name with optional filters, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'fetch_institution' for known IDs) 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 provide readOnlyHint=true, indicating a safe read operation. The description adds no further behavioral context such as pagination limits, rate limits, or response structure. The description does not contradict 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 that is clear and to the point, with no unnecessary words. It efficiently communicates the core functionality.

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 tool with 11 parameters and an output schema, the description is adequate but incomplete. It mentions key filter types but omits pagination (limit/page), sorting, and peer_reviewed_only. The presence of an output schema reduces the need to explain return values, but parameter usage could be clarified.

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 73% (8/11 parameters have descriptions). The description adds a generic 'and more' but does not elaborate on undocumented parameters like limit, page, or peer_reviewed_only. It provides minimal extra 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 'Search works in OpenAlex by keyword, filtered by...', providing a specific verb and resource. It distinguishes from sibling tools like fetch_work or fetch_author by focusing on search and filtering, and from semantic_search_works which is a different search method.

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 guidance on when to use this tool versus alternatives like semantic_search_works. The description implies usage for keyword-based search with filters but does not specify exclusion criteria or when not to use.

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, so description doesn't contradict. However, description adds no new behavioral insights (e.g., ranking details, performance). Output schema exists, so return values are covered; still, description misses opportunity to describe post-search ordering or result characteristics.

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 no wasted words. First sentence states purpose, second differentiates from keyword search. Front-loaded with key information.

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?

Description effectively communicates the tool's unique value (semantic vs. keyword) but does not mention output format, pagination, or limitations. Given output schema exists to document returns, description is largely complete for a search 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 description coverage is 70% (7 of 10 parameters documented). The description adds no extra parameter details beyond 'given text', which is already evident from the tool name. With high coverage, baseline 3 is appropriate; no added 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?

Description clearly states verb 'Find' and resource 'works', specifies 'AI-powered semantic search', and distinguishes from exact keyword match. This differentiates from sibling tools like search_works, which likely does keyword 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?

Description implies usage for semantic vs. keyword search but provides no explicit guidance on when to use this tool versus alternatives like search_works, nor any prerequisites or exclusions.

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