Islam West Africa Collection (IWAC)

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable behavioral context by explaining the return structure ({id, title, text, url, metadata}) and the semantics of 'text' (OCR/abstract/transcription/description) and 'url' (canonical link to cite). This goes beyond what annotations provide, though it does not discuss rate limits or error cases.

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-loaded with the main action, and contains no filler. Every sentence adds meaningful information about usage, return fields, and categories. It is efficiently structured and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only fetch tool, the description is highly complete. It covers the input, output format, field semantics, and possible categories. The output schema also exists, but the description's explanation of return fields ensures agent understanding without needing to inspect the 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?

The input schema already covers the 'id' parameter well with a description and example, and coverage is 100%. The description adds context about the format and origins from search, but this largely duplicates the schema. The extra category list is helpful but does not significantly change parameter understanding.

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's purpose: 'Retrieve the full text and metadata of one IWAC item by an id returned from search.' It specifies the resource (IWAC item), the action (retrieve), and the input mechanism, making it distinct from sibling get_* tools that target specific categories. The inclusion of categories and the 'category:number' format further clarifies its scope.

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 by instructing that the id must come from search and showing the expected format. It also lists valid categories, giving an implicit sense of when to use this tool. However, it does not explicitly mention alternatives like the get_* siblings or state when not to use it, so it stops short of full exclusionary 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, idempotentHint=true, and destructiveHint=false, so the bar for adding context is lower. The description exceeds it by disclosing the return payload (metadata, AI abstract, sentiment, OCR) and, importantly, noting that OCR is 'capped' and that passing a keyword switches to ~2000-char excerpts instead. This reveals behavioral nuances beyond simple read-only status.

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 with no filler. The first sentence states the primary function and return fields; the second explains the keyword alternative. Every sentence earns its place, and the structure is front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only single-entity fetch with no output schema, the description is complete. It tells the agent what data is returned, how the keyword parameter alters the response, and that OCR is capped. It sufficiently covers the tool's complexity without needing to explain structured return values since no output schema exists.

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% (keyword, max_excerpts, context_chars have descriptions; article_id lacks one). The description compensates for article_id by saying 'by id', clarifying its role. It also adds meaning to keyword by explaining it returns excerpts, and references the ~2000-char excerpt size aligned with context_chars default. This adds value beyond the 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?

The description opens with a specific verb ('Get') and resource ('one article by id'), then enumerates the exact returned fields (full metadata, AI abstract, AI sentiment, OCR text). This makes the tool's purpose unmistakable and distinguishes it from search-related siblings like search_articles, which are about finding articles rather than retrieving a single one's full details.

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 clearly states the tool fetches a single article by ID, implying it is intended when you have an article ID and need complete details. It does not explicitly mention alternatives or exclusions, but given the sibling tools (e.g., search_articles, get_document), the context of retrieving one specific article by ID is evident. The phrase 'Get one article (by id)' sets the appropriate usage boundary.

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 safety profile is clear. The description adds the list of returned fields, but no additional behavioral details (e.g., error handling, pagination, rate limits). This is adequate 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, front-loaded sentence that states the action and key fields. Every word earns its place; no fluff or repetition.

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 getter with one parameter and strong annotations, the description covers the core behavior and content. It does not specify return format, but no output schema exists and the field list suffices. Slightly more could be said about missing-record behavior, but it's not a critical gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions 'by id' but does not explicitly define audiovisual_id beyond the parameter name. The single parameter is self-descriptive, so the compensation is minimal and adequate, but not more.

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 action ('Get one audiovisual record by id') and the specific resource, distinguishing it from sibling tools like list_audiovisual and search_audiovisual. It also lists the included fields, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'by id' and 'one' clearly imply usage when a single audiovisual record's ID is known, differentiating from listing/searching. However, it does not explicitly name alternatives or mention when not to use it, so it falls short of the highest bar.

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. The description adds meaningful context by explaining that fulltext_coverage indicates how many items have searchable full text and warning about interpreting keyword counts, making the data quality caveat transparent.

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-loaded with the core purpose, and the second sentence adds a critical caveat without any fluff. Every word 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?

With no parameters and good annotations, the description covers the essential context: what the tool returns and how to use the fulltext_coverage metric. It does not enumerate every statistic, but the output schema exists, so that detail is not required. The warning adds completeness.

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 tool has zero parameters, so the baseline is 4. The description does not mention parameters, but none exist, and the schema is empty. The focus on output semantics is appropriate and adds 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 tool returns 'Overall statistics for every IWAC subset', which is a specific resource and scope. It highlights a key field (fulltext_coverage), but does not explicitly differentiate from sibling tools like get_newspaper_stats or get_temporal_distribution, so it falls short of a 5.

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 a clear usage context: 'Read that before treating any keyword count as a full-text census.' This tells the agent when this tool is useful. However, it does not mention alternatives or when not to use it, so it lacks explicit 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 tool is safe. The description adds that it returns 'the top values, the full symmetric matrix and the strongest pairs,' which provides some behavioral context beyond annotations, but does not disclose potential performance implications or data freshness.

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 long and front-loads the core purpose. It is clear without redundancy, but the final sentence specifying return values could be integrated more tightly with the first. Still, it earns a 4 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 output schema exists, the description covers return structure adequately. However, it lacks explanation of how multiple filter parameters (e.g., keyword and subject) interact, which may be necessary for complex queries. With high schema coverage, a 3 is fair.

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?

All 9 parameters have descriptions in the schema (100% coverage). The description adds minimal extra meaning, such as 'multi-valued field' and 'same item,' but the schema largely suffices. 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 clearly states the tool computes how often top field values co-occur on the same item, forming a subject/place co-mention matrix. It uses specific language ('co-occurrence matrix', 'top values') that distinguishes it from any sibling 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 the tool is for exploring co-occurrence patterns ('what is X discussed alongside') without reading items, but does not explicitly mention when to use it versus alternatives or provide exclusions. While the unique output type makes usage relatively clear, explicit guidance is missing.

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 safety profile is clear. The description adds useful context by specifying the exact metrics and the country dimension of the comparison, going beyond the annotations without contradicting them.

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 covers all necessary information without redundancy or filler. Every word contributes to the meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and an output schema present, the description fully communicates the tool's behavior by listing the compared metrics and the grouping dimension. There are no significant gaps, as the output schema likely details 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it adds value by describing what the comparison includes, which is sufficient for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Compare' and clearly identifies the resource (countries) and the four metrics being compared (article counts, newspaper counts, date ranges, gpt-5-6-luna polarity). This distinguishes it from siblings like get_field_distribution or get_collection_stats, which have broader or different scopes.

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 cross-country comparisons but provides no explicit when-to-use guidance or mentions alternative tools. For instance, it does not say to use a sibling tool for per-country details or other aggregations, leaving the choice less certain.

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 discloses that OCR text is capped and that keyword mode returns ~2000-character excerpts instead, which adds behavioral context beyond the readOnly/inidempotent annotations. It does not mention other potential behaviors like rate limits or errors, but the annotations already cover the safety profile, so this additional context is valuable.

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 long, front-loaded with the core purpose and then immediately explaining the optional keyword behavior. Every word contributes, with no filler or repetition, making it highly concise 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?

For a get-by-id tool with no output schema, the description clearly indicates what is returned (metadata, AI description, OCR text) and explains the keyword alternative. It also notes the OCR cap, which is an important detail. The annotations and input schema fill in safety and parameter details, making the overall tool description complete for an agent to invoke 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?

The schema already documents 3 of 4 parameters with descriptions (keyword, max_excerpts, context_chars). The description adds meaning for keyword by explaining the excerpt behavior and aligns with the default context_chars. However, it does not explicitly describe max_excerpts or context_chars beyond what the schema provides, and document_id lacks any description in both. With 75% schema coverage, the description moderately compensates but does not fully enhance all parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves one archival document by ID, specifying the contents (metadata, AI description, OCR text). The phrase 'archival document (by id)' distinguishes it from sibling tools like get_article or get_image, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: use this when you need a specific document's full details by ID. It also gives guidance for the keyword parameter, explaining when to use it (to get excerpts for long documents). However, it does not explicitly mention alternatives or when not to use this tool, so it lacks a direct exclusion statement.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds valuable behavioral context: pipe-joined fields are split (each value counted separately) and the over_time parameter returns per-year shares. This goes beyond what annotations 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 two sentences, both front-loaded with key information. The first sentence states purpose and gives clear examples; the second explains split behavior and optional over_time. 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 the tool's complexity (10 parameters, 1 required, output schema exists), the description covers the core functionality and key behaviors. It does not explain every parameter, but the schema and annotations handle that. Minor gap: no mention of return format, but output schema likely covers it.

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% with descriptions for all 10 parameters. The description adds some context (e.g., how pipe-joined fields are split, purpose of over_time), but these are largely covered by the schema descriptions. Baseline 3 is appropriate as the description does not significantly enhance parameter understanding beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool ranks values of a multi-valued field across a filtered set, with concrete examples ('which places does this coverage name most'). It uses a specific verb (rank) and resource (field values), and the examples help distinguish it from siblings like get_cooccurrence or 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?

The description implies this is the direct way to answer certain questions, but it does not explicitly state when not to use it or mention alternative sibling tools. For example, it lacks guidance on when to use get_cooccurrence instead. This leaves room for ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds value beyond annotations with the explicit statement 'The server returns URLs, not image bytes' and the detailed list of return fields, which helps the agent understand the exact shape of the response without an output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary action and resource, immediately followed by a useful caveat about URLs. Every word adds value; no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-by-id tool with a single parameter and no output schema, the description provides all necessary context: resource type, specific return fields, and the behavior regarding image bytes. The sibling list suggests this is part of a family of similar getters, and the description is sufficiently complete for an agent to invoke it 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?

The schema has one parameter, image_id, with no description coverage. The description's phrase 'by id' adds minimal context, implying image_id is an identifier, but it does not explain what kind of id (database key, API id) or how to obtain it. For a simple single parameter, this is adequate but leaves room for more clarity.

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 'Get one photograph by id' and enumerates the specific fields returned (title, photographer, capture date, place, coordinates, subjects, rights, IIIF manifest, image_url). This makes the purpose unambiguous and distinguishes it from sibling tools like get_audiovisual or get_document that target different resource 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 usage when you have a photograph id and need its metadata. It also provides an important exclusion: 'The server returns URLs, not image bytes,' guiding agents away from using this tool to download image data. However, it does not explicitly name alternative tools for byte retrieval or 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful context about the returned data (raw dataset columns, French names), but it does not disclose error behavior, response shape, or potential edge cases. This is acceptable but not exceptional given the annotation coverage.

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. It leads with the core action and resource, then provides a parenthetical with concrete field examples. Every word adds value, and there is no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, single-parameter, read-only tool, the description is largely sufficient: it names the input, the output nature, and clarifies the target resource. It does not mention possible errors or how to find the correct entry_id, but given the sibling set and the tool's low complexity, this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description only says 'by id', which is essentially a restatement of the parameter name entry_id. It does not explain how the ID is obtained, whether it is the internal database ID or a document ID, or what constraints apply beyond the schema's integer type. With 0% schema description coverage, the description should compensate but adds minimal semantic 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 tool's action ('Get'), the resource ('full details of an index entry'), and the lookup method ('by id'). It also gives concrete examples of returned fields (Titre, Prénom, Coordonnées), which distinguishes it from sibling get_* tools that target articles, documents, or references.

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 phrase 'by id' indicates the tool is used when the agent has a specific index entry ID and needs detailed information. It provides clear context for when to invoke the tool, though it does not explicitly mention alternatives 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 show readOnlyHint, idempotentHint, and non-destructive. The description adds crucial behavioral details: Lisibilite_OCR excludes non-French items counted in readability_excluded, MATTR is length-robust, and metrics exist only for public full-text items. This provides transparency beyond annotations without 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 about 100 words, front-loading the purpose then adding nuances. Each sentence adds value (e.g., clarifying metric behavior, language handling). However, it could be slightly more structured with bullet points or clearer separation of metrics, but it's efficient and concise.

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 output schema exists and the tool has 8 parameters with no required ones, the description comprehensively explains the metrics' interpretation, language filtering, and data availability. It covers key caveats without needing to describe the return structure (handled by output schema).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. The description does not add any parameter-specific semantics beyond what the schema provides. Each parameter is already well-described in the schema (e.g., top_n description includes default and max). Therefore, the description adds no extra value for parameters, staying at baseline 3.

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 computes readability, lexical richness, and length averaged by year, newspaper, or country. It specifies the exact metrics (Lisibilite_OCR and Richesse_Lexicale_OCR) and how they are computed. This distinguishes it from sibling tools like get_temporal_distribution which focus on trends, not lexical 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?

The description gives explicit usage guidance: 'do not normalise it by word count or bin it by length' for MATTR. It explains when to use each metric (readability only for French text, MATTR covers everything) and notes that metrics are only available for items with full text. While it doesn't explicitly compare to siblings, it provides clear context and constraints.

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, covering the safety profile. The description adds minimal extra context by summarizing the output (counts and date ranges) but does not mention any behaviors like pagination, filtering, or required permissions. It does not contradict annotations, so a mid-range score is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the core purpose without any wasted words. It is concise 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 the tool's simplicity (one optional parameter, full schema coverage, output schema present, and robust annotations), the minimal description is largely sufficient. However, it does not mention the optionality of the country filter or any usage caveats, which could be inferred from the schema but are not explicitly stated.

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 provides 100% coverage for the single parameter 'country', including a clear description and allowed values. The description does not add any additional parameter semantics, so the 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 identifies the resource (newspaper statistics) and the scope ('per-newspaper'), which distinguishes it from collection-level stats. However, it lacks an explicit verb, relying on the tool name 'get' to convey the action. It doesn't explicitly differentiate from siblings like get_collection_stats, but 'per-newspaper' provides enough context.

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. It does not mention any exclusions, prerequisites, or preferred use cases. Given the large sibling set, this omission weakens the agent's ability to select the correct 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds concrete behavioral details: only 555 of 683 'Lieux' entries are geocoded, non-geocoded places appear under 'ungeocoded', and other entity types never carry coordinates. This significantly enriches the agent's understanding.

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 (3 sentences) and well-structured: first sentence states the core functionality, second provides usage guidance, third adds an important caveat. No extraneous information or repetition of schema/annotations.

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 complexity (8 parameters, output schema), the description covers purpose, usage, and key behavioral aspects. However, it doesn't mention the default `top_n` value or max limit (though these are in the schema). The output schema exists to document return values, so this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides full descriptions for all 8 parameters (100% coverage). The description does not add any parameter-specific meaning beyond the generic 'filtered set of items', so it does not compensate beyond the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns places with coordinates from authority records, and explicitly distinguishes it from the sibling `get_field_distribution` for geographic questions. The verb 'get' and resource 'place distribution' are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Use this rather than get_field_distribution when the question is geographic... and the plain ranking when it is not.' It also clarifies that only 'Lieux' entries are geocoded, warning against using this for persons/organizations/events.

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 the readOnly/idempotent annotations, the description discloses accent-insensitive keyword matching, capped excerpts, and a subtle distinction between match_count and excerpts_returned. This is valuable behavioral context that helps set expectations about output limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. It efficiently conveys the main purpose and key optional behavior in under 25 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 there is no output schema, the description leaves some ambiguity about the return structure (e.g., what exactly match_count and excerpts_returned are, and whether full text is always returned). It provides a hint but not a complete specification of the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 50% schema coverage, the description partially compensates by explaining the role of keyword (excerpts around matches) and context_chars (~2000 chars). It doesn't clarify publication_id, but that is self-evident from the tool name. The capping mention also hints at max_excerpts semantics.

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 returns full OCR text of a publication and optionally excerpts around keyword matches. It is specific about the resource (publication) and operation, but it does not explicitly differentiate from sibling tools like get_document or get_article.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: use when you need full OCR text or keyword-matching excerpts. However, there is no explicit guidance on when to choose this over alternatives, nor any exclusions or prerequisites.

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

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

Annotations already indicate this is a safe, read-only, idempotent operation, so the description does not need to repeat those safety traits. It adds useful behavioral context by noting that the abstract is present for only ~51% of references, which is a data-quality caveat. It also explains the scope of the record, giving the agent an idea of what to expect without describing error handling or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that opens with the key purpose ('Full bibliographic record for one academic reference (by id)') and then efficiently lists the included components. Every word adds value, with no redundant phrases or filler. It is well-structured and easy to parse quickly.

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 a single parameter and no output schema, the description sufficiently covers what the tool returns by enumerating the record components and the abstract availability caveat. It does not mention the response format or error cases, but these are not critical for such a simple read operation. The description is appropriately complete given the tool's complexity.

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 schema has one parameter, reference_id, with type integer and bounds, but has 0% schema description coverage. The description compensates minimally by saying 'by id', clarifying that the parameter is the reference's identifier. However, it does not explain how to obtain a valid id or any other nuances. Given the parameter's self-explanatory name and the 'by id' hint, the description provides baseline but not rich semantic 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 tool returns a full bibliographic record for one academic reference by id, explicitly listing included fields such as abstract, subjects, DOI/URL, and host-work details. This distinguishes it from sibling tools like get_article or get_document, which target different resource types. The scope is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that the tool is used when a complete record for a single reference is needed, especially when the reference_id is known. However, it does not explicitly state when to prefer this over alternatives like get_article or get_document, nor does it mention any exclusions or prerequisites. The usage context is inferred rather than directly explained.

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?

Despite annotations already marking the tool as read-only/idempotent/non-destructive, the description goes well beyond: mentions no API key required, the embedding limitation ('only items whose full text ships are embedded at all'), the PCA variance caveat, and payload scaling behavior. This is rich, non-obvious 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?

Despite being longer than typical, every sentence earns its place: purpose, interpretation caveat, methodology distinction, auth, data availability, payload scaling, and practical advice. Front-loaded with the core function, then organized caveats. 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?

Output schema exists, so return values need no explanation. The description covers the tool's purpose, usage caveats, auth requirements, data limitations, scaling behavior, and interpretation warnings. Very complete for a tool with 9 optional parameters and a visualization output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds meaningful value for the 'limit' parameter by explaining its scaling impact and advising to keep it low for text-only clients, going beyond the schema's 'Items projected (default 300, max 2000)'.

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 opens with a specific verb and resource: 'A 2-D scatter of a filtered set, projected from the stored 768-dimension embeddings by PCA.' It clearly distinguishes the tool from siblings by noting 'This is PCA, not UMAP' and explicitly contrasts it with 'semantic landscapes on islam.zmo.de.'

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 solid usage context: instructs to read 'explained_variance' before drawing conclusions, warns that the payload scales with limit, and advises text-only clients to focus on the variance summary rather than coordinates. Does not explicitly name sibling alternatives like get_similar_items, but gives clear contextual 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 mark it read-only, idempotent, and non-destructive; the description adds substantial non-redundant behavior: three independent models, ordinal French labels, subjectivity being the weakest with a caveat, no OCR coverage limitation, and the intentional exclusion of ~51 non-francophone articles. This exceeds what the annotations convey.

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 dense but front-loaded with the purpose, and each subsequent sentence provides caveats or usage context. It is somewhat long, but every sentence earns its place given the tool's multi-model complexity.

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 complexity, the description covers all critical aspects: aggregation behavior, model agreement, scale characteristics, coverage caveats, and output comparison fields (scored_by_all vs total_articles). With annotations and an output schema present, no significant information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema documents model and country well, but subject and newspaper are bare string fields. The description adds meaning only for the model parameter (the 'all' option and the model roster) and refers vaguely to a 'filter set,' failing to clarify the two undocumented filters. It provides marginal value but does not fully compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Aggregate AI polarity, centrality and subjectivity across a filter set.' It clearly distinguishes this from sibling distribution tools by focusing on sentiment and the three-model agreement dimension.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit interpretive rules: use model:"all" to see per-model distributions plus agreement, and avoid quoting a single model's number when models disagree. It doesn't name alternative tools or when-not-to-use cases, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: no API key needed, it's per-item (not corpus-wide), and explains what similarity scores mean. 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?

The description is two paragraphs with front-loaded main action. It is informative but slightly verbose; however, every sentence adds value. Could be more concise, but still 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 rich annotations, full schema coverage, and output schema, the description is complete. It covers usage context, parameter interpretation, and behavioral traits sufficiently for an agent to invoke 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 coverage is 100%, but the description adds meaning beyond schema: it interprets the min_score parameter with concrete ranges (0.85+ syndication, 0.6-0.8 same subject) and clarifies the subset parameter implicitly. This helps agents choose appropriate 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 states the tool finds items nearest in meaning by cosine similarity over embeddings, answering 'what else is like this' without keywords. It distinguishes itself from sibling tools like search or get_article by specifying it uses embeddings for semantic similarity.

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 tool (find similar items without keywords, identify syndication or same subject) and explicitly contrasts with the corpus-wide near-duplicate sweep, which belongs offline. It also provides guidance on interpreting similarity thresholds (0.85+ for syndication, 0.6-0.8 for same subject).

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. The description adds substantial behavioral detail beyond annotations: undated items are counted in undated_count and never dropped silently; month-granularity keeps bare-year keys for items dated only to a year; hijri buckets require full YYYY-MM-DD, with imprecise dates reported in imprecise_date_count. Also explains the lunar_month collapsing behavior and the ~11-day drift reason. 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?

The description is long but each sentence earns its place. It fronts the main purpose, then covers subsets, filters, grouping, date precision handling, and the hijri calendar use case. The structure flows logically from general function to specific exceptions, and no sentence is redundant with the schema or annotations.

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 complexity (10 optional parameters, two calendars, group_by, and date precision edge cases), the description is remarkably complete. It covers all key behavioral aspects: counting aggregation, applicable subsets, filter compatibility, grouping behavior, and handling of undated/imprecise dates. An output schema exists, so return values are documented elsewhere. No major 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%, so baseline is 3. The description adds meaning beyond the schema: it clarifies that keyword is exactly ONE substring, explains the interaction between calendar=hijri and granularity=lunar_month (collapsing years into twelve lunar months), and specifies that group_by returns one distribution per group. It also names the shared filter set (country, newspaper/series, subject, date range) as 'the same filters as the corresponding search_* tool.' This enriches the parameter context enough to warrant a 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?

The description opens with a specific verb+resource ('Counts of matching items per year (or month)') and immediately differentiates from search tools by positioning itself as 'the direct way to chart coverage trends over time instead of paging through search results.' This distinguishes it from sibling distribution tools like get_field_distribution or get_topic_distribution by emphasizing the temporal dimension.

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: as a direct aggregation alternative to paging through search results. It also provides a strong exclusion/alternative note for the hijri calendar, calling it 'the ONLY way to see observance-driven coverage' (Ramadan, hajj, etc.), making clear when this tool is uniquely appropriate. No explicit 'when not to use' beyond the search alternative, but the context is unambiguous.

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 goes well beyond the annotations (readOnly, idempotent, non-destructive) by revealing the underlying model behavior: articles are 99.5% classified with 30 topics, while references have a separate 33-topic model with only ~46% classification. It also explains that topics are assigned offline over full text, meaning they describe content rather than surface word matches, and gives typical min_prob values with mean probability 0.34. This is rich behavioral context not available in 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 dense four-sentence paragraph, longer than the calibration HIGH example, but every sentence contributes useful information. It is front-loaded with the core purpose, then adds needed caveats and parameter guidance. Slightly verbose but not wasteful; 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?

Given that an output schema exists, the description does not need to detail return values, but it still clarifies important output nuances (e.g., 'read its classified against total_matches'). It provides essential context about topic model differences between articles and references, and explains over_time and min_prob behavior. It is complete for a read-only analytics tool with 10 optional parameters, though it could mention top_n more explicitly, but that is covered by the 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?

The schema already has 100% coverage for 10 parameters, so baseline is 3. The description adds practical guidance for over_time ('returns per-year counts for the leading topics') and min_prob ('keeps only articles where the topic is at least that dominant, mean 0.34, so 0.5 strong'), which supplements schema descriptions. It does not cover all parameters, but adds meaningful value for key ones.

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's purpose: distributing a filtered set across precomputed LDA topics, with topics labelled by top terms. It distinguishes itself from keyword counting ('use this instead of keyword counting') and from sibling distribution tools by focusing on topic-based semantic mapping. The verb 'get' plus specific resource ('topic distribution') is precise.

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 tells when to use this tool: 'use this instead of keyword counting to map a corpus' — a direct alternative. It also clarifies the difference between article and reference subsets, and explains how over_time and min_prob can be used for different analytical needs. This provides clear context for tool 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the specific content scope (Nigerian, Hausa/Arabic) which is useful context beyond annotations, but it does not disclose other behavioral aspects such as pagination behavior, ordering, or response structure. 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?

The description is a single sentence of 13 words, front-loaded with the core action. It contains no fluff, and the parenthetical adds essential scope information without redundancy. Every word 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 simple list tool with 3 parameters and no output schema, the description adequately conveys the main purpose and scope. The annotations cover safety aspects, and the schema provides parameter details. It could have explicitly mentioned the return type (e.g., 'returns a list'), but given the low complexity and rich annotations, the description is sufficiently complete.

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 schema has 67% coverage (limit and country are described), but offset has no description. The tool description adds no explanation of parameters; it only restates the content scope already present in the country parameter description. Thus it fails to compensate for the undocumented offset parameter, and the added value over the schema is minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') with a concrete resource ('audiovisual materials') and adds scope ('Nigerian recordings, incl. Hausa/Arabic content'). This clearly distinguishes it from sibling tools like list_locations or list_periodicals, and aligns with the tool's title.

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 need a listing of audiovisual materials, use this tool. However, it provides no explicit guidance on when to prefer this over alternatives like search_audiovisual or get_audiovisual, nor does it mention any exclusions. The scope statement gives some context but no direct comparison with siblings.

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

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

With annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral context: the list is sorted by collection-wide frequency, frequency is computed from articles + publications + references, and the Nigeria edge case is explained. These details go beyond the structured annotations and help the agent predict output behavior. It does not describe the return format, but that is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences: the first states the main purpose, the second explains the tricky filter semantics, and the third gives a concrete example. Every sentence earns its place, and key information is front-loaded. 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?

Given the complexity of the country filter, the description covers essential behavioral nuances and the frequency source, making it sufficient for a read-only list tool with pagination parameters documented in the schema. The only gap is the lack of explicit return field specification, but since no output schema exists and the tool is straightforward, this is not a critical 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?

Schema coverage is 67% (limit and country have descriptions; offset does not). The description significantly enriches the 'country' parameter by explaining that it selects mentioned-in entries and can include foreign/cross-border locations, plus the Nigeria caveat. This is more than the schema provides. Limit/offset are standard pagination parameters and need no further explanation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool does: lists lieux from the IWAC index, sorted by frequency. It specifies the resource ('lieux' from the IWAC index) and the ordering, distinguishing it from sibling list tools like list_persons and list_subjects. The country filter semantics further clarify the tool's scope.

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 on how to use the country filter, explaining the 'mentioned-in' versus 'located-in' distinction, which guides correct tool invocation. It also provides a concrete Nigeria example and the reason for the empty result. However, it does not explicitly name alternative tools (e.g., get_place_distribution) or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context by specifying the exact output fields (issue counts, year ranges) and the 'Islamic periodical/series' scope, which goes beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no filler. The first sentence states the action and scope; the second provides actionable next-step guidance. Every word 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 simple list tool with one optional parameter, a rich annotation set, and an output schema, the description fully covers the essential context: what the tool returns, its scope, and how the output should be used downstream.

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% because the sole `country` parameter is fully described with exact allowed values. The description adds no additional parameter detail, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and clearly identifies the resource ('Islamic periodical/series titles in the publications subset') plus the included data ('issue counts and year ranges'). This distinguishes it from sibling list tools like list_locations or list_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?

It provides explicit usage guidance: 'Use the returned newspaper value as the `newspaper` filter on search_publications.' This tells the agent when and how to use the tool relative to a concrete alternative, making the intended workflow 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?

Adds substantial behavioral context beyond the annotations: sorting order, the subtle 'mentioned-in' vs 'located-in' distinction, and the Nigeria-specific edge case rooted in frequency computation. These details are not disclosed by annotations and help an agent predict results, with 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?

Three efficiently packed sentences, each earning its place: purpose and sorting, parameter nuance, and a consequential edge case. The information is front-loaded with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no required parameters, the description covers the essential behavioral contract: what the tool lists, how it sorts, how the country filter behaves, and a notable edge case. It provides sufficient detail for an agent to invoke the tool correctly without additional documentation.

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 schema covers limit and country descriptions but not offset, totaling 67% coverage. The description adds significant nuance to the 'country' parameter, going beyond the schema by explaining the 'mentioned-in' semantics and the Nigeria outcome, enriching parameter understanding. Limit/offset remain standard and adequately covered by 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?

Clearly states it lists persons from the IWAC index, sorted by frequency, with a specific entity type that distinguishes it from sibling list tools. The verb 'List' and resource 'persons from the IWAC index' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context on when to use the country filter and explains its semantics ('mentioned-in' vs 'located-in') with a concrete Nigeria edge case. However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks full exclusionary 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 readOnly, idempotent, and non-destructive behavior, so the description's addition of sorting order is valuable context beyond those annotations. It does not mention pagination or result limits, but those are more parameter-related and partially covered by the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the verb and resource, with no filler or redundancy. The sorting detail earns its place by adding key behavioral 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?

The tool is simple and the annotations are rich, so the description covers purpose and sorting adequately. However, it lacks any mention of pagination or offset, and with no output schema, a hint about the return format would make it more complete for an 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?

The description adds no parameter information; the schema documents limit ('Default 50, max 200') but offset is left completely undocumented in both the schema and the description. With 50% schema coverage and no description compensation, the offset parameter remains unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' and identifies the resource as 'sujets from the IWAC index', clearly distinguishing it from sibling list_* tools like list_persons or list_audiovisual. The sorting detail ('most-referenced first') further clarifies what kind of list is returned.

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 a frequency-sorted list of subjects from the index is needed, providing clear context. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of full usage 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?

Even with annotations declaring readOnly and idempotent, the description adds substantial behavioral context: accent- and case-insensitivity, the multi-word 'every word must appear' rule, the preference for a single concept per call, and the shape of the response including `ranking` semantics. It also links to `fetch` for full-text retrieval, which goes beyond the structured 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 longer than average but every sentence delivers actionable information: scope, query constraints, language rules, response format, and alternative tools. It is front-loaded with the core purpose in the first sentence and maintains clear logical flow 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?

Given the tool's complexity (multi-domain search, multilingual requirements, custom ranking, and connection to `fetch`), the description covers all essential aspects: collection scope, query formulation rules, language handling, output structure, and disambiguation from filtered search tools. The presence of an output schema further reduces the need to document return values in prose.

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?

Although schema coverage is 100%, the description dramatically enriches the `query` parameter semantics by defining what constitutes a query (single concept/name), providing examples, explaining matching behavior, and prescribing language/transliteration conventions. This is far beyond the schema's 'One concept, name, or short phrase' 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 begins with a specific verb and resource: 'Search the Islam West Africa Collection', and enumerates the covered subsets (newspaper articles, Islamic publications, archival documents, etc.). It distinguishes itself from sibling search_* tools by explicitly stating 'For filtered queries (by country, date, or newspaper) use the search_* tools instead.'

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 on when to use this tool: for cross-collection searches with a single concept, and specifically directs filtered queries to sibling search_* tools as an alternative. It also gives actionable language instructions (French for press/publication/document/index, French/English for academic references) and transliteration rules (Tabaski, charia, Maouloud).

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: matching is accent- and case-insensitive, keyword searches across title, OCR, and AI abstracts in French and English, and the French-keyword preference. This goes beyond what annotations 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 two sentences, front-loaded with the core purpose, and the second sentence delivers essential keyword usage guidance. No redundant or wasted wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with 11 parameters and no output schema, the description covers the search scope, language handling, and matching behavior. It omits details like sorting or pagination, but the schema covers limit and with_description, so the overall context is reasonably complete.

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 73%, not high enough to fully rely on schema, but the description adds useful meaning to the keyword parameter (search scope, language) and lists searchable dimensions. It does not, however, explain the undocumented parameters like offset, subject, or newspaper beyond naming them, leaving some gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Search') and resource ('IWAC newspaper articles'), and lists concrete search dimensions (keyword, country, newspaper, subject, date range). This clearly distinguishes it from sibling tools like search_audiovisual or search_documents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly implies use for newspaper article search and gives a context-specific guideline: 'Use French concept keywords regardless of the user's report language.' However, it does not explicitly contrast with alternative search tools or state when not to use it, so it lacks explicit 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 mark this as read-only and idempotent, so the safety profile is covered. The description adds value by specifying which fields are keyword-searchable (title, creator, etc.), but it fails to disclose the current dataset limitation (all Nigeria) as noted in the 'country' parameter description, and does not mention pagination behavior.

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 short sentences with no filler. It front-loads the core purpose and adds a single clarifier for keyword behavior, making it highly concise and easy to parse.

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 complexity (7 parameters, no output schema), the description is adequate but not complete. It omits the Nigeria-only dataset constraint, which is important operational context, and doesn't describe result format or pagination, though these are partially covered by the schema and annotations.

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 86%, so the baseline is 3. The description goes beyond the schema by explicitly listing the fields matched by the 'keyword' parameter (title, creator, publisher, subject, spatial, language, source, AI description), which clarifies search semantics. It does not, however, elaborate on the 'medium' or 'country' filters, but the schema already describes them.

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 action ('Search') and the resource ('audiovisual materials'), and enumerates the fields that keyword matches, which distinguishes it from other content-type-specific search tools. However, it does not explicitly name alternative tools like 'list_audiovisual' for browsing, so it stops short of full sibling differentiation.

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 such as 'list_audiovisual' or 'search' for general searches. It only describes what the tool does, with no exclusions or alternative references.

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 the annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals that matching is accent/case-insensitive exact match, that labels are from one model and not a consensus, and that the subjectivity scale is the weakest. These are meaningful behavioral details not present in annotations, and there is 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 three sentences long, with the purpose stated first and each subsequent sentence providing a distinct caveat or alternative. There is no redundant or filler content; every 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 tool with 7 parameters and no output schema, the description covers model provenance, matching details, scale reliability, and points to an alternative tool. It does not explicitly describe the return format or pagination, but schema's limit/offset and read-only annotations partially cover this. Overall, it is well-contextualized for typical use.

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 schema already describes 5 of 7 parameters. The description adds important cross-parameter context: the matching behavior (accent/case-insensitive) and the weakness of the subjectivity scale, which affects how to interpret that parameter. However, offset and subject remain undocumented, and the description does not fully compensate for those gaps.

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 sentiment labels from a specific model (gpt-5-6-luna), distinguishing it from general search_articles and other search tools. It also references get_sentiment_distribution as a related but distinct tool, further clarifying its scope.

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 usage guidance by warning that the sentiment comes from a single model and recommends get_sentiment_distribution with model:'all' to assess disagreement. It also advises treating subjectivity-filtered results as leads rather than findings. However, it does not explicitly state when to prefer this over other search tools beyond the sentiment focus.

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 the annotations (readOnly, non-destructive), the description discloses the language handling requirement, the presence of OCR text and AI descriptions in most items, and the no-arguments listing behavior. These are valuable behavioral insights not captured 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 two sentences, front-loaded with the primary purpose. Every clause adds meaningful detail—scope, size, content, language guidance, and a shortcut—without any filler or 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?

The description effectively conveys scope, language, content type, and a usage shortcut. However, it does not mention pagination or offset behavior, and the 'list all' claim is ambiguous given the limit default. Nevertheless, with solid annotations and a straightforward parameter set, it is mostly complete.

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 useful keyword semantics (French, accent-insensitive) and a listing hint, but it does not explain the offset parameter, which lacks a schema description. More importantly, 'Call with no arguments to list all' appears inconsistent with the schema's default limit of 15, creating confusion about parameter 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's function with a specific verb and resource: 'Search the small archival-documents subset (~26 items...)' and provides scope details about the corpus content, distinguishing it from sibling search tools focused on other media 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?

It gives actionable context: 'Use French concept keywords regardless of the user's report language' and 'Call with no arguments to list all.' However, it does not explicitly mention alternatives or exclusions, and the 'list all' advice conflicts with the schema's limit default of 15, weakening the 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?

Beyond the read-only/idempotent annotations, the description reveals that captions are almost never present, that results include image_url, coordinates, and a canonical page, and that calling with no arguments lists all items. These are non-obvious behavioral traits that affect invocation and interpretation of results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, tightly packed with useful information: collection size, matching behavior, result fields, alternative tools, and usage tips. No filler or repetition; the structure front-loads the core purpose before adding nuance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description's enumeration of result fields (image_url, coordinates, page) is essential and provided. The 30-item scope, no-argument listing, and mention of semantic_search_images cover typical agent questions. The description is complete for a search tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (89%), so baseline is 3. The description adds value by explaining that keyword searches rarely match captions, that subject/place filters are preferable, and that these filters are 'pipe-aware' (though that detail is in the schema). It compensates for the few undocumented parameters by giving selection guidance rather than re-listing parameter syntax.

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 opens with a specific verb and resource: 'Search the IWAC photographs', and clearly defines the collection scope (30 items, content types). It distinguishes itself from siblings by focusing on photographs and even references semantic_search_images as an alternative, while the no-arguments listing behavior further clarifies its purpose.

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?

Explicit guidance is provided: captions are rare, so users should prefer subject/place filters over keywords, and semantic_search_images is named as an alternative. It also explains how to list all items, which covers the common 'no filter' use case. This directly helps an agent choose between this tool and siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context not in annotations: accent/case-insensitive matching and the 'by name' search behavior. This supplements the safety profile without contradicting it.

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 front-load the core purpose and add a useful matching behavior. Every word earns its place with 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?

Given moderate complexity (4 params, 1 required, no output schema), the description plus annotations and schema cover the essential aspects. It omits explicit pagination or return format, but these are not strictly necessary for a search tool with well-documented limit/offset parameters. The added accent/case-insensitive detail and clear scope make it sufficiently complete.

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% (limit, keyword, index_type have descriptions; offset lacks one). The description adds the 'accent/case-insensitive' nuance to keyword and confirms matching by name, but does not elaborate on limit, offset, or index_type beyond schema. With high schema coverage, 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 clearly states the tool searches the IWAC authority index, specifying the types of entries (persons, places, organisations, events, subjects) and that it matches by name. This distinguishes it from the generic 'search' sibling and other search 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 looking up authority entries by name, which is clear for an index search. It does not explicitly name alternative tools, but the specific resource scope provides context. No exclusions are stated, so it's a strong 4.

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, covering safety. The description adds non-obvious behavioral details beyond annotations: keyword matches full OCR text, TOC hits are returned as matching_toc_entries, and French concept keywords must be used regardless of the user's language. No contradiction exists.

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 concise three-sentence structure: purpose, keyword matching behavior, and filter/related-tool guidance. Every sentence carries useful information without redundancy, making it highly efficient and easy to parse.

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 10 parameters and no output schema, the description delivers essential context: what the tool does, how keyword matching works, which filters are available, and how to leverage adjacent tools. It does not detail the full response structure, but mentions the key TOC field, making it sufficiently complete for agent decision-making.

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 90% schema description coverage, the baseline is 3. The description adds extra meaning by explicitly noting that TOC hits come back as matching_toc_entries and emphasizing the French keyword requirement, which goes beyond what the schema states. This meaningful additional context justifies a 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?

The description clearly states the tool's purpose: search Islamic publications, specifically periodical issues and books. This distinguishes it from sibling tools like search_articles (individual articles) and search_documents. It also describes the specific matching behavior across title, subject, TOC, and 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?

The description provides clear context on how to use the tool (filter by newspaper/series, subject, country, year) and names related tools for complementary tasks (list_periodicals for series titles, get_publication_fulltext for excerpts). However, it does not explicitly state when not to use this tool versus other search variants, so it falls short of a 5.

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 the annotations (readOnlyHint=true, idempotentHint=true), the description discloses important behavioral traits: keyword is a single substring match over title+abstract, matching is accent-insensitive, metadata/filter values use French labels, and results include only a short snippet. This adds context that annotations do not provide and directly informs invocation 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 four sentences long, front-loaded with the primary purpose, then provides key usage caveats, and ends with a cross-reference to a sibling tool. Every sentence serves a distinct purpose (scope, search behavior, multilingual tip, result detail guidance), with no redundant phrasing or 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?

For a tool with 10 parameters and no output schema, the description adequately covers the most critical contextual aspects: the keyword matching behavior, multilingual considerations, French label conventions, and what results contain. It does not explicitly mention pagination defaults (limit/offset) or the exact list of reference types, but those are already present in the input schema, so the description is complete enough for effective use.

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 schema already covers 80% of parameter descriptions, but the description adds extra semantics for the keyword parameter (substring match, one term per call, accent-insensitive) and clarifies that reference_type and language use French labels. This goes beyond simply restating schema descriptions, though the high schema coverage means the description does not need to compensate heavily.

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 opens with a specific verb ('Search') and a resource ('academic references') followed by a parenthetical list of reference types (journal articles, book chapters, theses, books, reports), clearly scoping the tool's function. It also distinguishes itself from sibling search tools by specifying the exact search mechanism ('by keyword and metadata') and later clarifying the substring-match limitation, which differentiates it from broader search 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 provides explicit usage guidance: 'search ONE term per call' with a concrete example of a failed combined query ('pèlerinage Mecque'), and advises trying both French and English keywords. It also tells when to use get_reference instead ('use get_reference for the full abstract and bibliographic detail'), which clearly directs the agent to an alternative tool when more detail is needed.

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