Islam West Africa Collection (IWAC)

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the description adds value by detailing the return structure (fields: id, title, text, url, metadata) and explaining what 'text' and 'url' represent. This goes beyond the annotations to provide concrete behavioral expectations.

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 compact: two sentences that cover purpose, id format, return fields, and categories. Every sentence adds essential information, and the most critical details (what it does and how to use it) are 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?

With only one parameter and a straightforward behavior, the description covers the essential aspects: what it retrieves, how to identify items, and what the output looks like. It doesn't discuss error cases (e.g., invalid id), but given the presence of an output schema and the tool's simplicity, this is a minor omission.

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 'id' with a description, but the tool description adds the specific format '<category>:<number>' with an example. This provides practical guidance beyond the schema, helping the agent construct valid values.

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 specifies the action ('Retrieve'), the resource ('IWAC item'), and the source of the identifier ('an id returned from search'). It also defines the id format and lists categories, which helps the agent understand what kind of item to expect. The tool is distinct from sibling get_* tools by being a generic fetcher for any category, and the description makes this clear.

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 gives clear context: use this tool after performing a search, as the id comes from the search tool. It does not explicitly exclude any situations or mention alternative tools like get_article, but the context is strong enough for an agent to infer when it's 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?

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that OCR is capped and keyword returns excerpts, providing some behavioral context beyond annotations, but lacks details like auth requirements or error handling.

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 well-structured sentences, front-loaded with purpose and key return fields, no wasted 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?

Given no output schema, the description lists return fields (metadata, AI abstract, Gemini sentiment, OCR text) and excerpt behavior. It is fairly complete for a straightforward retrieval tool, though could specify return format structure.

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 baseline is 3. The description adds context for keyword (returns excerpts) and references ~2000-character excerpts, aligning with context_chars default, but does not significantly elaborate beyond schema for max_excerpts or context_chars.

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 retrieves one article by ID with full metadata, AI abstract, Gemini sentiment, and OCR text. It distinguishes from siblings like search_articles (search) and get_document (document retrieval).

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 for fetching a single article by ID, and mentions keyword for excerpts, but does not explicitly state when to use this tool vs alternatives like search_articles or get_document, nor provides when-not guidance.

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 idempotentHint=true, so no contradiction. The description adds value by enumerating the fields returned (creator/publisher, media URL, etc.), which goes beyond annotation hints.

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, 13 words, front-loaded with main action, no 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?

No output schema, but the description lists the fields included. It doesn't cover error conditions or pagination, but for a get-by-id tool, the information is sufficient.

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%, but the description clarifies that the parameter 'audiovisual_id' is the identifier. However, it does not provide additional context like format, range, or examples, which would be needed for full compensation.

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 gets one audiovisual record by id and lists the fields returned. It distinguishes from siblings like list_audiovisual (which returns multiple) and search_audiovisual (which searches).

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 you have an id and need details, providing clear context. However, it does not explicitly state when not to use or mention alternatives like search or list tools.

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, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds the scope 'for all six IWAC subsets' but lacks additional behavioral context like data freshness or default behavior. 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?

Single sentence that is clear and to the point. No wasted 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?

Given zero parameters, rich annotations (all hints present), and an output schema, the description is complete. It sufficiently describes the tool's purpose and scope.

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?

Input schema has zero parameters, so schema coverage is 100%. Description adds no parameter info, but baseline for zero parameters is 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?

Description states it provides overall statistics for all six IWAC subsets, using a specific verb+resource. It distinguishes itself from sibling tools like get_newspaper_stats or get_sentiment_distribution by focusing on aggregate statistics across all subsets.

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 overall statistics for all six IWAC subsets are needed, but does not explicitly state when not to use it or provide alternatives. No guidance on exclusions or 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 provide readOnlyHint, idempotentHint, and destructiveHint. Description adds that it compares specific metrics but does not elaborate on behavioral aspects like whether all countries are returned at once, pagination, or any side effects. With annotations covering safety, a score of 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?

Single sentence that is concise and front-loaded. Every word is meaningful, with no superfluous 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?

For a tool with no parameters and an existing output schema, the description is mostly complete. However, it does not clarify whether the comparison spans all available countries or requires an implicit selection. The output schema is assumed to explain the return format.

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?

Input schema has 0 parameters, so baseline is 4. Description does not add parameter details, but none are needed. Schema coverage is 100% for an empty 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?

Description clearly states the tool compares article counts, newspaper counts, date ranges, and Gemini polarity across countries. It specifies both the action and the resource, and distinguishes it from sibling tools like get_newspaper_stats or get_temporal_distribution which focus on single-country or single-dimension metrics.

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 on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or how to decide between this and other get_* or search_* tools. Users are left to infer context from the tool name and 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 indicate read-only and idempotent behavior. The description adds context about the return format (full metadata, AI description, OCR text) and the conditional behavior with keyword (excerpts vs capped OCR). 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?

The description is two sentences: first states purpose and outputs, second explains the keyword mode. No redundant information, front-loaded with key details.

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?

Lacks details on output structure (no output schema) and error conditions. However, with readOnlyHint and clear purpose, return values are somewhat inferable. Could mention required permissions or additional behavioral context.

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% (3 of 4 params described). The description adds meaning by explaining the purpose of keyword (excerpts for long documents) and reinforces defaults for max_excerpts and context_chars, which are already in 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 specifies the verb 'get', resource 'archival document', and output 'full metadata, AI description, and OCR text'. It also distinguishes from siblings by focusing on documents with OCR and AI description.

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 explicit guidance for using the keyword parameter to get excerpts instead of full OCR, stating it is 'useful for long documents'. However, it does not explicitly contrast with siblings or specify when not to use the 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 and idempotentHint. The description adds useful behavioral context about the output content (raw columns, French names), which is not redundant 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?

Single sentence, no redundancy, front-loaded with key information. Every word adds value.

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 no output schema, the description gives a sufficient overview of what is returned. It could mention the response format or include an example, but it is adequate.

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?

With 0% schema coverage and only one parameter, the description adds no meaning beyond the schema. It does not explain the entry_id parameter's format, source, or usage.

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 retrieves full details of an index entry by ID, specifying the resource and the nature of details (raw dataset columns, French names). It distinguishes from sibling tools for other entity types.

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 you have an entry_id, but provides no explicit guidance on when to use this tool versus alternatives like get_article or get_document. No context on prerequisites or exclusions.

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 destructiveHint=false, so the description doesn't need to add safety info. However, it doesn't explain behavioral details like whether it returns counts per newspaper across the given country or overall. The description is adequate given annotations 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?

The description is a single concise sentence with no wasted words. It front-loads the core functionality and earns its place.

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 an output schema exists, the description doesn't need to explain return values. However, it doesn't clarify behavior when the optional 'country' parameter is omitted, or how 'per-newspaper' grouping works. Some 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 coverage is 100%, and the schema's description for 'country' is detailed with exact allowed values. The description adds no additional meaning beyond the schema, so baseline 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 'Per-newspaper article counts and date ranges' clearly states what the tool returns (article counts and date ranges per newspaper) and distinguishes it from siblings like get_collection_stats or search. However, it could be more precise by noting that the input is a country.

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 on when to use this tool versus alternatives like get_collection_stats or search. The description lacks context for when a user should choose this over other statistics or search tools.

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, idempotentHint=true, destructiveHint=false. The description adds that matching is 'accent-insensitive' and excerpts are 'capped', but does not detail the cap behavior or explain 'match_count vs excerpts_returned'. It adds some behavioral context beyond 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 of about 20 words, front-loading the primary function ('Full OCR text of a publication') and then succinctly adding the optional excerpt feature. Every word adds value; no redundancy.

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 is provided, so the description must explain return values. It states the tool returns full OCR text and optionally excerpts, but does not clarify the structure without keyword (e.g., full text only) or explain 'match_count vs excerpts_returned' adequately. Basic completeness, but leaves gaps for effective selection.

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 beyond the schema: it links context_chars to '~2000-char excerpts', mentions accent-insensitivity for keyword, and hints at a cap for max_excerpts. This compensates for the schema's 50% description coverage, especially for keyword and context_chars which lack schema descriptions.

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 'Full OCR text of a publication' with optional excerpts, providing a specific verb and resource. It distinguishes from siblings like search_publications by focusing on content retrieval, but does not explicitly differentiate from get_document or other similar tools.

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 for retrieving full text and optionally excerpts around keyword matches, but lacks explicit guidance on when to use this tool versus alternatives like search_publications or get_document. No exclusions or when-not scenarios are provided.

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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds that the abstract is present for ~51% of references and includes subjects, DOI/URL, and host-work details, providing valuable behavioral context.

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 efficiently conveys the tool's purpose and included details without any waste.

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 no output schema, the description fully sets expectations by listing contents and noting the abstract's partial availability.

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 single parameter 'reference_id' is self-explanatory, and though schema description coverage is 0%, the description adds no extra meaning to the parameter beyond what the name implies.

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 full bibliographic record for one academic reference by ID, distinguishing it from sibling tools like 'get_article' or 'search_references' by specifying the details included.

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 full bibliographic details of a single reference are needed, but does not explicitly state when not to use or provide alternatives, leaving it to context from sibling tools.

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, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is clear. The description adds that it aggregates counts, but doesn't disclose any behavioral specifics beyond that. With annotations present, this is adequate but adds limited new context.

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, concise, and front-loaded with the verb. However, it lacks necessary detail to be fully informative, and every part is essential but still incomplete.

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 that an output schema exists, the description doesn't need to explain return values. However, the input parameters are only partially documented, and the term 'Gemini' is ambiguous. The tool's purpose is somewhat clear but could be more complete for effective agent usage.

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% (only 'country' has a description). The tool description does not explain the meaning or usage of 'subject' and 'newspaper' parameters, nor how they form a filter set. The description should compensate for the low schema coverage but fails to do so.

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 aggregates 'polarity and centrality counts' using a specific verb 'aggregate' and mentions filtering. However, it doesn't explain what 'Gemini' refers to, and while it distinguishes from fetching tools, it's similar to other aggregate tools like get_temporal_distribution.

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 on when to use this tool versus alternatives like get_temporal_distribution or search. The description does not specify prerequisites, when not to use it, or mention any exclusions.

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?

Description adds valuable behavioral context beyond annotations: handling of undated items (bare-year key, undated_count), behavior with month granularity for year-only items, and group_by behavior. Annotations already provide readOnlyHint, so bar is lower, but description significantly enhances 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?

Single concise paragraph, front-loaded with primary purpose, logically structured: purpose, alternative, filter list, grouping options, edge case handling. No superfluous text.

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 9 parameters, no required params, and presence of output schema, description covers all essential aspects: main function, filter compatibility, grouping, granularity behavior, and undated item handling. Fully adequate for an agent to use correctly.

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 covers all 9 parameters with descriptions (100% coverage). Description adds cross-tool context (filters same as search_* tools), optional group_by semantics, and granularity edge cases. Adds value beyond schema without redundancy.

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 verb 'counts' and resource 'matching items per year or month', distinguishes from sibling search tools by emphasizing 'direct way to chart coverage trends over time instead of paging through search results'.

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 (charting trends over time) and references alternative approach (paging through search). Lists accepted filters that match sibling search tools, implying contextual usage. Lacks explicit when-not-to-use statement but is clear enough.

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, destructiveHint. Description adds a note about current content count and languages, which is contextual but not additional behavioral disclosure. No contradiction 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?

Single sentence, very concise. However, the mention of 'currently 45 recordings' is temporary and may become outdated, slightly reducing maintainability.

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 list tool with pagination, the description is minimal. No mention of return structure (likely an array of items), which could be inferred but is not explicit. Lacks guidance on filtering beyond the country parameter.

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 67%, with descriptions for limit and country but not offset. The description does not elaborate on parameter usage or valid values beyond what schema provides, so it adds no extra 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 'List audiovisual materials' with a specific resource type and scope ('currently 45 Nigerian recordings, incl. Hausa/Arabic content'). Distinguishes from siblings like 'get_audiovisual' (singular) and 'search_audiovisual' (search vs 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?

No explicit guidance on when to use this tool versus alternatives like 'search_audiovisual' or 'get_audiovisual'. Does not mention prerequisites or contexts where listing 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds behavioral details: sorting by frequency, the country filter interprets appearance in records, and the specific case of Nigeria having no entries. 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 concise sentences: the first states purpose and sorting, the second details the country filter with context. Every sentence provides value, and the structure is front-loaded with the core function.

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 sufficient for understanding the tool's behavior, but it does not explain the output format (e.g., what fields are returned). Since there is no output schema, the agent might need to infer or test the return structure. However, the core functionality is well-covered.

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 significant meaning to the 'country' parameter beyond its schema description, explaining the semantics of 'mentioned-in' vs 'located-in' and providing an example with Nigeria. With 67% schema coverage, the description compensates well for the offset parameter lacking a 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 lists 'lieux' from the IWAC index, sorted by frequency (most-referenced first). This distinguishes it from sibling tools like 'search' or 'list_persons' by specifying the resource and ordering.

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?

Provides explicit guidance: explains the optional 'country' filter semantics (mentioned-in vs located-in), gives an example that Nigeria returns none due to data composition, and clarifies that foreign/cross-border entries can appear. This helps the agent decide when to use this 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 and idempotentHint. The description adds detail about output (issue counts, year ranges) and the usage pattern of the returned newspaper value, enriching behavioral context without 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?

Two sentences, no wasted words. The first sentence states purpose and output, the second gives usage guidance. Highly 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 one parameter with full schema, no required params, and presence of an output schema, the description sufficiently covers the tool's functionality and usage. The agent can determine inputs and how to use results.

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 only parameter, country, has 100% schema coverage with a clear enumeration. The description does not add further meaning beyond the schema, so 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 that the tool lists Islamic periodical/series titles with issue counts and year ranges, specifying it is within the publications subset. It also distinguishes from siblings by directing the use of the returned newspaper value for filtering on search_publications.

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 explicitly instructs to use the returned newspaper value as a filter for search_publications, providing clear guidance on when and how to use the tool, and implying the alternative tool for searching.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds that sorting is by frequency and explains the country filter's behavior, including why Nigeria returns none. This provides useful context beyond 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 concise (three sentences) and front-loaded with the main purpose. Every sentence adds value without redundancy.

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?

Without an output schema, the description explains the sorted list and country filter behavior, including an edge case. It does not describe pagination, but the schema covers limit/offset. Overall adequate for a list 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 67%, with limit and offset described in the schema. The description adds significant meaning for the 'country' parameter, explaining it selects mentions rather than locations and how frequency is computed. This compensates for the lack of schema description for offset.

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 personnes from the IWAC index, sorted by frequency. It distinguishes from sibling tools like list_locations and list_subjects by specifying the resource and sorting order.

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 explains when to use the country filter and clarifies its semantics (mentioned-in vs. located-in). It provides an example for Nigeria. However, it does not explicitly state when not to use the tool or compare with alternatives.

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, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds the sorting behavior ('sorted by frequency, most-referenced first'), which provides useful context beyond the annotations, but does not cover pagination or other behavioral details.

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 with no wasted words. It efficiently conveys the purpose and a key behavioral detail.

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 list tool with two parameters and no output schema, the description is adequate but lacks details on return format and parameter constraints beyond the schema. The presence of many sibling tools suggests additional context could be beneficial.

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% (only 'limit' has a description). The tool description does not add any meaning to either parameter, failing to compensate for the missing 'offset' documentation.

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 'List' and the resource 'sujets from the IWAC index', with added sorting context. It distinguishes itself from sibling tools by specifying a unique resource type, though it does not explicitly differentiate from other list tools.

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. The description only states what it does, without any context on when to prefer it over sibling list tools 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, destructiveHint, idempotentHint. Description adds behavioral details: matching behavior, return format with categories and ranking, and that id leads to fetch for full text. 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?

Description is detailed but well-structured, with purpose first then specifics. Could be slightly more concise, but front-loading and organization are good.

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 complexity (multiple collections, many sibling tools), the description is comprehensive: covers scope, usage, matching, language tips, output format, and relation to other tools. No gaps noted.

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% for both parameters. Description adds meaningful usage guidance: query should be one concept in French, limit default 20 max 50. Adds nuance beyond schema but schema already describes basics.

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 the tool searches across multiple named collections (newspapers, Islamic publications, etc.) with a single concept or name. Distinguishes from sibling tools by directing filtered queries to search_* tools and mentioning fetch for full text.

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 instructs to pass ONE concept or name, use French terms, gives examples, explains matching behavior (accent/case-insensitive, multi-word requirement), and provides alternatives for filtered searches.

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 read-only, idempotent, non-destructive behavior. The description adds value beyond annotations by specifying the search fields (title, OCR, AI abstract), language requirement, case-insensitivity, and the token-cost warning for the with_description parameter. This provides helpful behavioral context.

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. The first sentence front-loads the core purpose and searchable fields. The second sentence provides essential usage nuance. Every word earns its place; no 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?

The description covers the main search behavior, language specificity, and a practical note on the with_description parameter. However, it omits result ordering (e.g., by relevance or date) and how multiple parameters combine (AND vs OR). Given the complexity of 9 optional parameters, a bit more completeness could help, but it's still fairly solid.

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%. The description adds meaning for the 'keyword' parameter (French concept) and 'with_description' (token cost warning), but other parameters like country, newspaper, and date range are only listed without additional nuance. Schema already covers basic descriptions, so the tool description adds moderate 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?

The description clearly states the verb 'Search', the resource 'IWAC newspaper articles', and the scope: by keyword across title, OCR, and AI abstract, plus filters for country, newspaper, subject, and date range. This explicitly distinguishes it from sibling tools like search_documents or search_audiovisual.

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 explicit guidance: 'Use French concept keywords regardless of the user's report language' and 'Matching is accent- and case-insensitive.' It implies this tool is for articles, but does not explicitly state when to avoid it or mention alternative tools for other document types, which would increase clarity.

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 readOnly, idempotent, non-destructive behavior. Description adds that keyword matches multiple fields, but no further behavioral context like pagination or rate limits. Consistent, but minimal added value.

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, no redundancy. First sentence states core purpose, second provides key detail. Efficient and well-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?

Given 7 parameters and no output schema, description adequately explains search scope and fields. Does not need to duplicate schema details like default limits or exact medium values. Sufficient for agent understanding.

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 covers 86% of parameters with descriptions. Description adds context about keyword matching specific fields (title, creator, etc.) not in schema, which is useful. Baseline 3 due to high coverage, plus slight improvement.

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 describes the tool as searching audiovisual materials by keyword and metadata, with specific fields listed. Distinguishes from sibling such as list_audiovisual which likely lists all items.

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 search, search_articles, or list_audiovisual. Does not mention when not to use or provide 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?

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that matching is accent/case-insensitive exact, which is useful. No other behavioral traits (e.g., pagination, sorting) are mentioned.

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, front-loading the key action. It is concise but could be improved by structuring details (e.g., separating parameter info).

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 no output schema, the description should indicate what the tool returns (e.g., list of articles, counts). It does not, leaving the agent uncertain about the response. Also, with 6 parameters, more context on usage would help.

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%. The description adds meaning to the polarity and centrality parameters by listing their values. However, limit and offset only have basic schema descriptions; full meaning is not further clarified.

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 filters articles by AI sentiment labels, with details on exact matching. It distinguishes itself from general search siblings but does not explicitly differentiate from other search variants.

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 on when to use this tool versus alternatives like search_articles or get_sentiment_distribution. The agent must infer from the purpose alone.

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 indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing the small dataset size, the presence of OCR and AI descriptions, and that a no-argument call returns all items. 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?

The description is three sentences, front-loading the most important information (scope, language hint, no-arg behavior). It's efficient but the third sentence could be slightly more polished.

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 4 parameters and no output schema, the description covers dataset size, language, and no-arg listing, but does not specify result format, ordering, or edge cases. For a simple search tool, this is adequate but incomplete for full understanding.

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 the schema already describes most parameters. The description reinforces the language hint for keyword but doesn't add significant new semantics beyond what's in the schema. The 'call with no arguments' hint is helpful for limit and offset default behavior.

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 a specific archival subset (~26 items) and lists content types (Islamic association reports, flyers, etc.) and geographic focus (mostly Burkina Faso). This distinguishes it from sibling search tools like search_articles or search_audiovisual.

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 gives explicit guidance to use French concept keywords regardless of user language, and indicates that calling with no arguments lists all items. While it doesn't explicitly state when not to use it, the scope is clearly defined, and alternatives are implied by sibling tool 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 and idempotentHint, so the description adds value by explaining accent/case-insensitive matching and that keyword is matched against entry title. It does not cover pagination or error behavior, but the annotations reduce the burden.

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 with no extraneous words. It is front-loaded with the key action and resource, then adds the important matching detail.

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 has 4 parameters and no output schema, the description covers the core purpose and matching behavior but omits details on pagination (limit/offset) and error handling for invalid index_type. It does not specify return format, leaving some gaps for the agent.

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 75% (3 of 4 parameters have descriptions). The tool's description adds context for the keyword parameter ('by name') and matching behavior but does not address the offset parameter which lacks schema description. Overall, the schema carries most of the parameter meaning.

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 the IWAC authority index for entities like persons, places, organizations, events, and subjects by name. It distinguishes from sibling tools like 'search' by specifying the authority index scope and adding case/accent insensitivity.

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 clear usage context: searching for authority entries by name with case-insensitive matching. However, it does not explicitly state when not to use this tool or mention alternatives, relying on sibling names for differentiation.

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 indicate readOnlyHint=true and destructiveHint=false. The description complements these by detailing search behavior (substring match, accent-insensitive, French keywords) without contradicting annotations. It adds useful context beyond the structured fields.

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 concise with three sentences, front-loaded with the primary purpose. No unnecessary words; each sentence earns its place.

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 search tool with 8 optional parameters and no output schema, the description covers key aspects: search scope, filters, and sibling tool references. It does not mention pagination or result structure, but this is acceptable given the parameter schema details.

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 high (88%), so baseline is 3. The description adds marginal value by explaining keyword search scope (title, subject, OCR) and French keyword requirement, but most parameter details are already in 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 that the tool searches Islamic publications (periodical issues, books) and specifies that keyword matches title, subject, and full OCR text. It also mentions filters by newspaper/series, subject, country, and year. However, it does not explicitly differentiate from sibling search tools like search_articles or search_documents, leaving some ambiguity.

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 specific guidance: use French concept keywords regardless of user language, and references sibling tools list_periodicals and get_publication_fulltext for related tasks. It does not explicitly state when not to use this tool, but the 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?

Beyond annotations (readOnlyHint, idempotentHint), the description reveals keyword substring matching behavior, multilingual considerations, and reference_type partial matching quirks. This adds valuable behavioral context not present in structured fields.

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 concise (three sentences) and front-loaded with the main purpose. Every sentence adds essential information without redundancy or 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 10 parameters and no output schema, the description adequately explains key behaviors (substring matching, multilingual search, reference_type matching) and directs to get_reference for full details. Coverage is sufficient for a search tool with high schema description coverage.

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?

With 80% schema description coverage, the description adds nuance: keyword must be a single term, reference_type values use French labels and substring matching, and language uses French labels. This enhances the schema's bare property descriptions.

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 searches academic references and lists resource types (journal articles, book chapters, theses, etc.). However, it does not explicitly differentiate from sibling tools like search_articles or search_audiovisual, leaving some ambiguity for an AI agent.

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 specific guidance: keyword is a single substring match, search one term per call, use multilingual keywords, metadata uses French labels, and suggests get_reference for full details. It does not explicitly state when to avoid this tool in favor of siblings.

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