Islam West Africa Collection (IWAC)

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

Annotations already carry readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: filters intersect, coverage reports archive availability, exports are paginated and identify page plus dataset snapshot, and snapshot/compare IDs should be reconciled across pages.

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?

Dense and front-loaded: the mode list leads, followed by behavioral constraints. Most clauses earn their place, though the first sentence is a long run-on enumeration that could be broken for clarity.

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 complex multi-mode tool with nested objects and an output schema, the description covers modes, export/pagination semantics, and the iwac:// schema-discovery URI. Combined with annotations and the output schema, an agent has enough to invoke it correctly, with only subset/limit semantics left implicit.

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?

Top-level schema description coverage is 0%, so the description must compensate. It effectively documents the `mode` enum values and the cross-parameter dependency for `compare`, but says nothing about `limit`, `offset`, or the `subset` enum members, leaving part of the parameter surface unelucidated.

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 names a specific dispatchable resource ('Selection workbench') and enumerates all nine modes it supports, plus the exports it can produce. An agent can tell this is a corpus-exploration router, though it does not explicitly contrast itself with the many search_*/list_* siblings, leaving mode-to-sibling routing to inference.

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 one hard usage rule ('compare (requires comparison)') and frames each mode's intent (coverage = availability, exports = paginated). However, it never states when to reach for explore_corpus rather than search_articles, search, or the get_* tools, so the alternative-selection guidance is only implied.

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 mark it read-only and idempotent, and the description adds value by detailing the exact return shape and semantics of fields (text, url, metadata). It doesn't contradict annotations, and explains more than the raw 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 a single dense sentence that efficiently packs purpose, return shape, and categories without 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?

For a simple one-param read tool, the description covers purpose, input format, output shape, and categories. It omits error handling and alternative tool selection, but with an output schema present and good annotations, it's nearly 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 already describes id with examples, and the description reinforces the format and adds a list of valid categories, providing useful context beyond the schema for correct formatting.

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

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

The description clearly states it retrieves an IWAC item by id and describes the return payload. However, it does not explain how this generic fetch relates to the many category-specific get_* siblings, so differentiation is missing.

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 after search and for all listed categories, but it doesn't explicitly state when to prefer this tool over category-specific getters, nor does it list any exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds real behavioral context beyond them — 25k-char part sizing, the next_offset follow-up pattern, and the ~2000-char excerpt mode. It does not state auth needs 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?

Two dense sentences, front-loaded with the core retrieval action and paging behavior; no filler. Slightly compressed but every clause carries 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?

No output schema, so the description carries return-value burden, which it handles by listing metadata, abstract, sentiment, and OCR text plus the paging contract. Minor gaps remain around excerpt count defaults and error cases.

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 80%, so most parameters are already documented. The description still adds meaning: offset is framed as 'the previous part's next_offset' and keyword is described as producing ~2000-char excerpts around each match, clarifying the interaction between the two 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?

States a specific verb and resource ('Get one article') and enumerates the payload ('full metadata, the AI abstract, AI sentiment, and OCR text'), which distinguishes it from search_articles. It stops short of naming siblings explicitly, so not a full 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?

Implies usage via 'by id' and the paging/keyword modes, but never states when to prefer this over search_articles or the other get_* siblings. The keyword-mode condition is clear, but alternative routing is left to inference.

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 the safe-read profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior beyond them: transcription paging at 25k-char parts with next_offset, keyword excerpts as an alternative, source_type as the signal for which link applies, and which of the three URLs is the citation-grade one.

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?

Front-loads verb+resource, then packs return fields and link disambiguation into compact clauses, closing with pagination/keyword behavior. Every sentence carries information an agent cannot get from the schema or annotations; no filler.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly, including the ambiguous three-URL case and transcription truncation. An agent has enough to call correctly and interpret the response without guessing.

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

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

Schema coverage is only 33% (only offset is documented in the schema), so the description must compensate. It does: 'keyword returns excerpts instead' defines the otherwise-bare keyword param, and 'follow next_offset' clarifies the offset semantics. audiovisual_id is self-evident from 'by id', leaving only minor 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?

States a specific verb and resource ('Get one audiovisual record by id') and then enumerates the actual fields returned (description, transcription, creator/channel, duration, medium, subjects, places, language, rights, source, and the three link types). This lets an agent distinguish it from list_audiovisual/search_audiovisual purely on the 'by id, single record' 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?

Clearly establishes the trigger context ('by id') and explains two invocation variants within the tool: paginating a long transcription via next_offset and using 'keyword' to get excerpts instead of the full part. It does not name a sibling tool to route away to, so it stays short of a full 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, non-destructive, so the safety profile is covered. The description adds real behavioral value by explaining what `fulltext_coverage` measures and warning that keyword counts are not full-text censuses — a non-obvious caveat an agent would otherwise misuse.

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 tight sentences with zero filler. The scope statement comes first and the interpretive warning second, which is the right front-loading for a stats tool.

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?

An output schema exists, so return values need not be enumerated, and the description spends its budget on the one nuance that matters. For a parameterless read-only stats call, this is close to complete; only cross-tool routing guidance 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 tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. It does not need to compensate for any schema 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?

States a specific verb and resource: overall statistics for every IWAC subset, plus the named `fulltext_coverage` metric. The scope ('every subset') implicitly separates it from the narrower `get_newspaper_stats` and `get_field_distribution`, though it never names those siblings explicitly.

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

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

It gives one strong interpretive directive — read `fulltext_coverage` before treating a keyword count as a full-text census — which is genuinely useful. But it offers no guidance on when to reach for this tool versus the many sibling stats/distribution tools, so usage is only implied.

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 establish read-only, idempotent, non-destructive behavior, and the description still adds real value: filters are applied before pair counting, top_n caps the vocabulary, and results are descriptive associations rather than causal links. It doesn't cover ordering of output rows or how ties are broken, but the operational semantics disclosed are substantive.

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 short sentences, each carrying distinct information (what is counted, how to interpret it, and filter/top_n semantics), with the core purpose front-loaded and no filler.

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

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

For a tool with 14 parameters, an enum, nested objects, and an output schema, the description is thin: it explains the computation and one parameter but leaves the filter vocabulary, subset scope, and keyword modes unaddressed. The output schema relieves it of explaining return values, but the input surface is under-described.

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 57% across 14 parameters, and the description only illuminates top_n ('caps the vocabulary') and the generic notion of filters. Undocumented parameters such as subset, keyword_mode, field, and the Hijri/date options receive no compensating explanation. The added meaning is real but narrow.

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

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

States a specific verb and resource: 'Count pairs of metadata values co-tagged on the same items,' which clearly identifies a co-occurrence computation. It does not name or contrast with the nearest siblings (get_field_distribution, get_semantic_map, get_topic_distribution), so an agent must infer the boundary from the title alone.

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 only guidance is interpretive ('Matrix/network views show descriptive associations, not causal links') and a filter-ordering note. There is no statement of when to choose this tool over get_field_distribution or get_semantic_map, nor any prerequisite or exclusion conditions.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond them: the 25k-character chunking, the follow-`next_offset` paging protocol, and the keyword-mode excerpt behavior. It doesn't address auth needs or edge/error cases, keeping it just short of a 5.

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

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

Two tightly packed sentences that are front-loaded with the primary behavior (fetch one document by id) followed by the alternative mode. No 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?

With no output schema, the description carries the return-value burden and does so by naming the returned fields and the pagination mechanism. It is nearly complete for a read-only getter, though it omits error/not-found behavior and explicit auth expectations.

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

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

Schema coverage is already 80%, so baseline is 3. The description goes further by explaining that offset should be set to the previous part's next_offset and by characterizing keyword mode's excerpt semantics, adding meaning beyond the schema text.

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

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

The description states a specific verb and resource ('Get one archival document (by id)') and enumerates the payload (metadata, AI description, OCR text), which is far more informative than a tautology. It does not explicitly name or contrast against close siblings like get_article or get_publication_fulltext, 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?

It gives clear conditional guidance for the keyword path ('Pass a keyword to get ~2000-char excerpts... useful for long documents'), which implies when to use it. However, there is no explicit when-to-use/when-not guidance relative to sibling retrieval tools such as search_documents or get_article.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive) and open-world status. The description adds behavioral value beyond that: it discloses tag-splitting behavior, that missing metadata is reported, and that over-time coverage is optional, which the annotations do not 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?

Three tight sentences, appropriately front-loaded with the core action ('Rank exact metadata values') before behavioral and field-choice details. Nearly every clause earns its place, though the final field-selection sentence is somewhat crammed.

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

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

With 15 parameters and nested objects, the description is thin: it covers the key field decision and the over_time behavior, and the output schema handles return values. But it leaves most filters and options (subset, top_n default, date ranges, keyword modes) unexplained, so it is only minimally adequate for a 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 60%, so the description must partially compensate. It clarifies the most important parameter (field) by explaining the meaning of spatial vs country vs subject/author/language values, and hints at pipe-separated tag handling and the over_time option, but says nothing about the many filter parameters (exact, subset, keyword, hijri_year, etc.).

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

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

The description states a specific verb and resource ('Rank exact metadata values') and adds scope detail ('splitting pipe-separated tags'). However, it never distinguishes this tool from distribution siblings like get_place_distribution or get_topic_distribution, leaving the agent to infer the relationship.

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 sentence 'Choose spatial for mentioned places, country for stored country tags, or subject/author/language' gives explicit field-selection guidance, but it addresses parameter choice rather than when to use this tool over an alternative. There is no routing to or from sibling tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower, yet the description adds a genuinely useful trait: 'The server returns URLs, not image bytes,' which prevents an agent from expecting binary content. It also compensates for the absent output schema by listing returned fields. It does not mention not-found/error behavior, so not a 5.

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

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

Two sentences, zero filler, front-loaded with the action and scope before the caveat about URL vs bytes. Every clause carries 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?

With no output schema, the field enumeration is essential and present, and the URL-not-bytes caveat closes the main expectation gap. Only error/not-found behavior is unaddressed, which is minor for a read-only lookup.

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?

Only one parameter and schema description coverage is 0%, so the schema contributes nothing about image_id. The description only says the lookup is 'by id,' conveying that it is an identifier but not its type, format, or provenance. Partial compensation, minimum-viable.

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

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

States a specific verb and resource ('Get one photograph by id') and enumerates exactly which fields come back (title, photographer, capture date, place, subjects, rights, IIIF manifest, image_url). An agent can distinguish this single-record fetch from the numerous search_* and list_* siblings without opening either schema.

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 only implied: retrieve one photograph by its id. There is no explicit when-to-use guidance, no mention of when to prefer search_images instead, and no statement about what happens for an unknown id. Adequate but leaves routing to inference.

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, so the safety profile is covered. The description adds genuinely useful context beyond that: the entry contains raw dataset columns with French field names (Titre, Prénom, Coordonnées), telling the agent what kind of data comes back.

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

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

A single front-loaded sentence with the action first and a compact parenthetical illustrating the payload. No filler, though the trailing ellipsis leaves the field list open-ended rather than fully specifying.

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 one-parameter read tool with rich annotations and no output schema, the description covers the operation, the lookup key, and the shape of the returned content. Only the origin/format of entry_id is left unstated.

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% and the single parameter entry_id is undocumented in the schema, so the description must carry it. It only says 'by id', which names the key but gives no type, format, or where the id originates, leaving a real 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?

States a specific verb (get) and resource (index entry) with the lookup key (id), which distinguishes it from the sibling search_index by retrieval mode. It stops short of explicitly naming the sibling alternative, so it is clear but not fully differentiated.

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 by 'by id' — an agent infers this is the follow-up call when it already has an entry_id. There is no explicit when-to-use statement or reference to search_index as the way to obtain an id first.

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

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

Annotations already declare this as a safe, idempotent, non-destructive read. The description adds genuinely non-structured behavioral context: metrics are precomputed, readability is French-specific and excludes other languages, and missing values are disclosed. This is useful caveat-level detail beyond the annotations.

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

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

Four short sentences, front-loaded with what is returned, followed by caveats and intended use. Efficient with little waste, though the grouping scope and caveats could be ordered slightly more tightly.

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-format explanation is unnecessary, and annotations cover safety. But for a 13-parameter tool with nested objects and only 54% parameter coverage, the description leaves substantial filtering behavior undocumented, making it only minimally complete for its 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?

With 54% schema coverage across 13 parameters, the schema documents roughly half. The description ties outputs to country/newspaper/year (mapping to group_by) but adds no syntax or meaning for the other parameters such as exact, keyword_mode, or keyword_aliases. It compensates only marginally for the coverage gap, so a 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 names a specific resource (text length, lexical richness, readability) and its grouping dimensions (country/newspaper/year), which lets an agent recognize this as the lexical-metrics retrieval tool. It is clear but does not explicitly distinguish itself from sibling distribution tools like get_field_distribution 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?

'Compare distributions as descriptive evidence' implies the intended analytical use, giving some guidance. However, there is no explicit when-to-use vs. when-not, and no mention of alternatives among the many sibling distribution/corpus tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, 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?

Annotations already establish readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds real value by disclosing output semantics (separation of publication vs. mentioned places, explicit counting of missing geocodes), but says nothing about filtering behavior, pagination, or how top_n interacts with 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?

Two tight sentences with no filler, front-loaded with the core resource mapping. The phrasing is dense to the point of being slightly cryptic ('joined to authority coordinates'), but nothing is wasted.

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 13-parameter, zero-required-parameter tool with only 54% schema coverage, the description supplies no filtering, scoping, or top_n guidance an agent would need to call it correctly. The output schema covers return values, but the invocation side is largely unaddressed.

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 54%, so roughly half the parameters lack documentation, and the description contributes no parameter information at all beyond the vague phrase 'place tags'. With 13 parameters including nested exact-filter semantics, the description does not 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 names a specific resource (place tags joined to authority coordinates) and what the tool produces (a geographic distribution). It doesn't explicitly distinguish itself from siblings like get_semantic_map, get_country_comparison, or list_locations, so sibling differentiation is left to inference.

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?

There is no guidance on when to use this tool versus the many other distribution/map tools in the sibling list. The 'separates publication countries from mentioned places' note is about output composition, not about when to choose this tool.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds real operational context beyond that: 25k-char paging units, next_offset-based traversal, ~2000-char excerpt windows, accent-insensitive matching, and result capping visible via match_count vs excerpts_returned.

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

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

A single front-loaded sentence that leads with the primary purpose (full OCR text) before the excerpt alternative. Dense with parentheticals but each clause carries distinct information; no filler.

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

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

For a read-only paging tool with no output schema, the description names the key return signals (next_offset, match_count, excerpts_returned) and both operating modes. It stops short of fully specifying the response envelope, but annotations cover safety and the paging contract is clear.

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 schema coverage at 60%, the description compensates well: it explains offset as following the previous part's next_offset, that keyword matching is accent-insensitive, and that excerpt/context output is capped. It adds meaning beyond the terse schema entries, though it doesn't tie every parameter to its 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?

States a specific resource (a publication's full OCR text) and distinguishes two retrieval modes: paged full text versus keyword excerpts. An agent knows exactly what it gets, though it does not name or contrast against siblings like search_publications or get_document.

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 'or' construction implicitly tells the agent it can either page the whole document or pull keyword-context excerpts, and the next_offset reference implies chained paging. However, there is no explicit when-to-use guidance versus the many sibling search/get tools, so usage must be inferred.

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 non-destructive behavior, so safety is covered. The description usefully adds that the abstract is only present for ~51% of references, setting expectations on missing data, plus the set of host-work fields returned.

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

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

A single front-loaded sentence that leads with the verb and resource, then packs field-level detail with zero 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, the description compensates by enumerating returned fields (abstract, subjects, DOI/URL, host-work details) and flagging the abstract's sparse availability. Safety is covered by annotations, leaving little an agent would need that isn't present.

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?

One parameter with 0% schema description coverage, so the description carries the burden. 'by id' signals that reference_id is an identifier, but adds no format, source, or validity detail beyond the schema's integer type.

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

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

States a specific verb and resource ('Full bibliographic record for one academic reference') scoped clearly by id, and enumerates the returned fields, which lets an agent separate it from list/search tools. It does not explicitly name the sibling search_references, 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 'one academic reference (by id)' scoping implies you call this once you already have an id, typically from search_references, but no explicit when-to-use or when-not-to-use guidance is given. Usage is only inferable.

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 cover readOnly/idempotent/openWorld, and the description adds meaningful behavior beyond them: it is a sampled hash projection (not exhaustive), reports eligible/invalid/missing/capped counts plus seed and explained variance, coordinates are chart-only, and no API key is needed. The 'capped' and 'sample' notes are genuinely useful context a caller needs.

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?

Four compact sentences, front-loaded with the projection method and sample semantics, then the disambiguation caveat. No filler; each sentence carries distinct 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?

An output schema exists, so return value detail is not required, and the description still flags what the numbers mean (eligible/invalid/missing/capped, explained variance). Given the high parameter count, filter semantics are under-explained, but the core behavioral picture is complete for a charting tool.

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

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

With 14 params and 57% schema coverage, the burden is shared. The description adds only loose meaning ('matching', 'capped sample') and does not clarify the many filter params (keyword_mode, keyword_aliases, hijri_*, date_to) left undocumented in the schema. Marginally better than schema-only but not compensating 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?

States a specific operation and output: a stable-hash sample of matching embeddings projected with PCA into a scatter. The scope ('sample', 'chart-only') is clear. It distinguishes itself from a similar published landscape only implicitly via the UMAP contrast, not by naming a sibling tool.

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

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

No explicit when-to-use guidance against the many siblings (get_topic_distribution, get_similar_items, get_cooccurrence, etc.). The description clarifies only the negative boundary ('not the published UMAP landscape') but gives no positive criteria for choosing this tool over alternatives.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds substantive context beyond them: it discloses that kappa results come with explicit denominators and, importantly, that labels are model interpretations rather than ground truth and that subjectivity is weak evidence requiring a caveat. That interpretive framing is real behavioral value the annotations cannot 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?

Four dense sentences with no filler; the mode semantics are front-loaded after a short opening clause. The closing caveat sentence is slightly editorial but carries a genuine usage warning, so it 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 an output schema present, return values need no explanation, and the description covers the distinctive behavior (aggregation modes, pairwise agreement metrics, interpretive caveat) adequately. Coverage of the many filter parameters is thin, but those are largely self-documenting in 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?

Schema coverage is only 50% across 14 parameters, so the description must compensate, and it does so for the most consequential ones: it explains the semantics of model:"all" vs "consensus" and the role of compare_models plus agreement_field in producing Cohen's and quadratic weighted kappa. The remaining filter parameters (hijri_*, keyword_mode, keyword_aliases) are left to the schema.

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

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

The description gives a clear verb ('Aggregate') and resource ('AI labels over a shared selection') and explains the two headline modes, model:"all" and model:"consensus". However, it never says the tool produces a sentiment *distribution* of counts, and it does not distinguish itself from the similar-sounding siblings get_field_distribution or get_topic_distribution, so the agent must infer the distinction.

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

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

It gives explicit conditional guidance for the mode parameters: use model:"all" to compare independent annotators and coverage, model:"consensus" for the stored panel majority, and add compare_models/agreement_field for pairwise kappa. What is missing is any guidance on when to choose this tool over siblings such as search_by_sentiment or get_field_distribution.

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, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: local embedding lookup with no API key, scores as ranking hints rather than proof, and the scope limitation that bulk candidate generation must be done offline.

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?

Four short, front-loaded sentences with no filler; the core operation leads and the cautions follow. The telegraphic phrasing ('no threshold proves a reprint') is dense but each sentence carries distinct 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?

An output schema exists, so return values need not be enumerated, and annotations cover the safety profile. The description supplies the interpretive cautions and scope limits an agent needs to use the scores correctly, leaving little missing for a four-parameter lookup tool.

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

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

Schema description coverage is 100%, so id, limit, subset and min_score are fully documented in the schema. The description adds no syntax, default, or interpretation detail for any parameter, which is the expected baseline when the schema does the work.

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

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

States a specific operation on a specific resource: nearest stored embeddings ranked by cosine similarity, computed locally 'without an API key'. That clearly separates it from the search_* family, though no sibling is named explicitly.

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

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

Gives both a use case ('scores rank reading candidates') and a negative boundary ('corpus-wide candidate generation belongs offline'), plus a caution that 'no threshold proves a reprint'. It stops short of naming which alternative tool to use for corpus-wide work.

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 establish read-only, idempotent, non-destructive semantics, so the bar is lower. The description still adds real value by disclosing data-quality caveats (partial dates and missing lunar dates are disclosed) and the precise normalize_by behavior (per-bucket denominators, removal of thematic filters from the denominator).

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?

Four sentences, front-loaded with the core counting/bucketing behavior, with no wasted filler. The IWAC-holdings sentence is somewhat jargon-heavy but still purposeful.

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?

An output schema exists, so return values need not be explained, and the description covers the main temporal axes and normalization. However, with 16 parameters and only 63% schema coverage, filtering options like keyword_mode and the nested 'exact' object remain unexplained, leaving gaps for a complex tool.

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

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

Schema coverage is 63%, so the schema carries much of the burden. The description usefully clarifies calendar, granularity (pooled lunar month), group_by, and normalize_by semantics, but leaves several parameters (exact, keyword_mode, keyword_aliases, subset, subject) undocumented in the description text.

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 operation: counting records bucketed by Gregorian/Hijri year, month, or pooled lunar month, with optional country/newspaper grouping. This clearly identifies it as a temporal-coverage distribution tool distinct from distribution siblings. It does not, however, name any sibling (get_field_distribution, get_topic_distribution, get_country_comparison) to sharpen the boundary.

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 by the capabilities listed (grouping, bucketing, normalization), but there is no explicit when-to-use/when-not or routing to an alternative. An agent must infer that this is the tool for time-series coverage versus the other get_*_distribution tools.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context beyond that: topic labels are interpretive model outputs (a reliability caveat) and the result reports unclassified coverage, plus optional over-time 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?

Three tight sentences, front-loaded with the core capability before the caveats. Every clause adds information; nothing is filler, though the interpretive-model caveat could be slightly more prominent.

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 15-parameter analytical tool this covers the interpretive caveat and the unclassified-reporting behavior well, and an output schema exists so return values need no explanation. However, usage selection against sibling distribution tools and roughly 40% of undocumented parameters are left unaddressed.

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 60% with 15 parameters, including a nested 'exact' object. The description meaningfully clarifies exact.topic_id semantics ('select assignments rather than keyword matches') and nods to over_time, but says nothing about subset, min_prob, top_n, hijri_*, keyword_mode or keyword_aliases, so it only partially compensates 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?

Opens with a specific verb+resource ('Counts of offline LDA topic assignments') and explicitly frames the assignment-vs-keyword distinction, which separates it from search tools. It is clear what the tool returns, though it never names or contrasts a sibling like get_field_distribution or get_semantic_map.

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 only implied: an agent can infer you call this when you want topic counts, and the exact.topic_id note warns against expecting keyword matching. There is no explicit when-to-use statement, no exclusions, and no routing to alternative distribution tools for other facets.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). The description adds genuinely useful non-schema context: results are ordered newest-first and the corpus is limited to specific francophone West African sources. It omits return shape and pagination semantics, so it is helpful 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?

A single front-loaded sentence: purpose and ordering first, filters last. The parenthetical corpus detail is dense and partly overlaps the country param description, but it earns its place by scoping the tool.

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, zero-required-param list tool with strong annotations and an 80%-covered schema, the description supplies the ordering and corpus scope an agent needs. With no output schema, a brief note on result shape or paging would be the only remaining 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 80%, so the schema already explains limit, country, publisher and source_type. The description only restates the filter names (country, channel, source_type) without adding format or syntax detail, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List audiovisual materials'), plus sort order ('newest first') and the corpus scope (francophone web video from Burkina Faso, Togo, Benin; deposited Nigerian Hausa/Arabic recordings). It does not, however, distinguish itself from the sibling search_audiovisual, so the agent must infer the list-vs-search boundary.

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 enumerates the available filters (country, publishing channel, source_type), which implies how to narrow results, but gives no explicit when-to-use guidance or exclusion relative to search_audiovisual. Usage is implied rather than stated.

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

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

Annotations already declare this a safe, idempotent, non-destructive read. The description goes beyond them by disclosing the ranking logic (index frequency computed from articles + publications + references), the cross-border/foreign-result behavior, and the Nigeria edge case — real behavioral context an agent needs. Return shape is still unstated.

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?

Purpose and ordering are front-loaded in the first clause, then the country caveats follow. The parenthetical Nigeria explanation is long but earns its place as a genuine edge case; overall slightly dense but 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 list tool with no output schema and no annotations gap, the description covers filtering and ordering well, but never describes the entry fields returned (name? frequency value? country?). An agent can call it but cannot anticipate the payload shape.

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%, but the description adds decisive semantics the schema only hints at: 'country' selects entries MENTIONED IN records from that country, not located there, and ranked by collection-wide frequency. That materially changes how an agent interprets the filter, though limit/offset behavior is left to the schema.

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

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

States a specific verb and resource ('List lieux from the IWAC index') plus the ordering ('sorted by frequency, most-referenced first'), so the agent knows exactly what comes back and in what order. It doesn't explicitly distinguish itself from the nearby list_persons/list_subjects/search_index siblings, keeping it just 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?

Provides strong conditional guidance around the 'country' filter, including an explicit negative case ('Nigeria returns none here' because the index frequency draws on articles/publications/references). It never names an alternative tool for the filtered cases, so it lacks full when-to-use/when-not routing.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds genuinely non-obvious behavior: the sort order, the mentioned-in vs located-in distinction, and the Nigeria-returns-nothing quirk with its cause. Only the limit/offset and result-shape behavior are left unspecified, and there is no output schema to cover 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?

Front-loads the core operation and sort order, then the optional filter and its caveat. The long parenthetical on index frequency is dense but earns its place by explaining why Nigeria yields no results.

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 3-parameter read-only lister with no output schema, the description covers purpose, ordering, filter semantics, and a surprising edge case. It does not describe pagination behavior or the shape of returned entries, which are the remaining gaps.

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

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

Schema coverage is 67% and the schema's own country description already explains the mentioned-in semantics in near-identical terms. The description reinforces this and adds the Nigeria edge case, but does not clarify limit/offset beyond what the schema says, so it sits at the baseline for a partially documented 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?

States a specific verb+resource (list personnes from the IWAC index) plus the ordering rule (sorted by frequency, most-referenced first), which is enough to distinguish it from sibling listers like list_locations and list_subjects without opening a schema.

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 conditional context: the 'country' filter selects mentioned-in rather than located-in entries, and it explicitly warns that Nigeria returns none and why. It stops short of naming an alternative tool (e.g. search_index) for name-based lookup, but the filter-routing guidance is strong.

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 assert readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false, so safety is covered. The description adds useful behavioral context by stating results are sorted by frequency (most-referenced first), which is not in the annotations. It does not cover pagination behavior or return limits.

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

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

A single, front-loaded sentence with no filler. It communicates the resource, source index, and sort order efficiently.

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 rich annotations, the description covers the resource and ordering, but it leaves the offset parameter undocumented and gives no usage routing among many sibling list/search tools. No output schema exists, so return values need not be explained, but the pagination gap keeps it from being fully 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 only 50%: limit is documented as 'Default 50, max 200' while offset has no description. The description does not mention either parameter or explain pagination, so it fails to compensate for the undocumented offset.

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

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

The description states a specific verb ('List') and resource ('sujets') scoped to the IWAC index, and specifies sort order by frequency. This distinguishes it from generic search or get tools, though it does not explicitly contrast with sibling list_* tools.

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

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

No when-to-use guidance, prerequisites, or alternatives are given. The sorting note hints at the output but does not tell an agent when to choose list_subjects over list_persons, list_locations, or search_index.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds substantial behavioral context beyond them: accent/case-insensitive matching, AND semantics for multi-word queries, required French query language, prescribed transliterations, and the return shape with a pointer to fetch. This is rich, actionable disclosure.

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?

Front-loaded with the resource and scope, and every sentence is useful. Slight redundancy between 'Pass ONE concept or name' and 'prefer a single concept per call', and the language/transliteration instructions could be tightened, keep it from a 5.

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-category search, multilingual corpus, large sibling set) the description covers routing, language protocol, query construction, and result handling. An output schema exists, so it needn't detail return values, and the brief return summary is appropriately minimal.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully enriches the query parameter with matching semantics (multi-word AND logic), language requirements, and transliteration guidance that go beyond the schema's brief note. The limit parameter is only echoed, not added to.

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

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

States a specific verb ('Search') and resource ('Islam West Africa Collection') and enumerates the covered subsets precisely. It distinguishes itself from sibling tools by explicitly routing filtered queries to the 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?

Provides explicit when-to-use (concept/name lookup), when-not-to-use (filtered queries by country/date/newspaper → search_* tools), and how-to-use guidance on query language, transliteration, and single-concept calls. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral detail: matching is accent- and case-insensitive, and keyword scans title + OCR + both AI abstracts — semantics an agent could not derive from the annotations. It omits result ordering and 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?

Two dense sentences with no filler, and the scope statement is front-loaded before the keyword-language rule. Slightly over-packed parentheticals, but every clause carries information.

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

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

For a complex, 14-parameter, nested-object tool with no output schema, the description delivers the essentials: what corpus is searched, which text fields the keyword hits, and the French-keyword rule. The many advanced parameters and the `exact` object are left entirely to the schema, which is acceptable given the schema does document them.

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 14 parameters and only 64% schema description coverage, the description names roughly five facets (keyword, country, newspaper, subject, dates) but says nothing about exact, limit/offset, hijri_year/month, keyword_mode, keyword_aliases, or with_description. Its one added nuance — which fields the keyword matches and accent/case insensitivity — is useful but partial, so it neither compensates fully nor is purely redundant.

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 names a specific verb and resource ('Search IWAC newspaper articles') and enumerates the facets searched (keyword, country, newspaper, subject, date range), which cleanly separates it from get_article or the stats tools. It stops short of naming the neighboring search_* siblings (search_documents, search_index, search_publications), so the agent must still infer which corpus each covers.

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 line 'Use French concept keywords regardless of the user's report language' is a concrete, actionable usage rule and is genuinely helpful. However, it gives no guidance on when to prefer this tool over search_documents or search, and no prerequisites/exclusions are stated, leaving the selection decision to inference.

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

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

Annotations already cover readOnly, idempotent, closed-world, non-destructive, so the bar is lower. The description adds real value beyond them: the full list of fields keyword matches (including the item's own description and transcription) and the guarantee that each row carries either external_url or media_url, never both.

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?

Purpose is front-loaded in the opening clause, then detail follows. Sentences are dense but each earns its place by conveying searchable-field and return-shape information; slightly long but not padded.

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?

A read-only search tool with zero required params and no output schema. The description compensates by describing populations, searchable fields, and row structure. Complete enough to call correctly, with only alternative-routing guidance left out.

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

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

Schema coverage is already 89%, so the baseline is 3. The description enriches keyword semantics by enumerating the matched fields beyond the schema's generic 'title/metadata', and clarifies source_type as two populations (youtube majority vs 47 deposited records), adding meaning over the schema.

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

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

The description gives a specific verb+resource (search audiovisual materials) and details the exact populations covered (Burkina Faso/Togo/Benin web video, deposited Nigerian Hausa/Arabic recordings). It distinguishes itself from generic siblings by content, though it never explicitly names alternatives like search_documents or get_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?

No explicit when-to-use, when-not-to-use, or alternative routing is provided. The population description implies the tool's scope but gives no conditions or guidance on choosing it over the many search_* 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 cover the safe-read profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: accent/case-insensitive exact-match semantics, the fact that this reflects one model's reading rather than a consensus, and that subjectivity is the weakest scale. These are material behavioral disclosures an agent cannot infer from 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 core operation and matching semantics are front-loaded in the first sentence, followed by two sentences of interpretation caveats that each carry real information. Dense but no filler.

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

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

No output schema exists, so return values need not be described, and the description covers the key interpretive risks (single-model reading, weak subjectivity scale) plus an alternative tool. Complete enough for an 8-param read-only filter.

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

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

Schema coverage is 75% and the schema already documents limit, country, disputed, and the three sentiment fields including the subjectivity exclusion rule. The description adds only the model identity and the relative weakness of the subjectivity scale, so it sits at the baseline for schema-heavy coverage rather than compensating for a 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?

States a specific verb+resource (filter articles) scoped to gpt-5-6-luna sentiment labels, and explicitly names the sibling get_sentiment_distribution for the cross-model view. An agent can distinguish this from search_articles and get_sentiment_distribution without opening a schema.

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?

Routes the agent to get_sentiment_distribution with model:"all" when cross-model disagreement matters, and warns that a set selected on subjectivity should be read as a lead, not a finding. This gives clear when-to-use context and a caution about interpretation, though it never states explicit exclusions for polarity/centrality use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only, idempotent operation. The description adds valuable corpus-size and language context, but doesn't elaborate on pagination behavior, rate limits, or how OCR/AI descriptions affect results beyond their existence. With annotations covering the safety profile, this meets the baseline for added 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?

Three compact sentences, each earning its place: corpus scope, language guidance, and no-args behavior. Front-loaded with the most critical differentiator (subset size) and free of 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 adequately covers what an agent needs: corpus size, dominant country, language for keywords, and no-arg fallback. Missing details on pagination defaults (limit default 15, max 50) are left to the schema, and no output schema means the agent might wonder about return format, but the core operational picture is 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% (3 of 4 parameters documented), so the schema does most of the heavy lifting. The description mentions keyword (French concept keywords) and implies country via 'mostly Burkina Faso', but adds no syntax or format details beyond the schema's own descriptions.

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

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

States a specific verb (Search) and resource (archival documents), and immediately scopes it to 'the small archival-documents subset (~26 items)'. This distinctively differentiates it from siblings like search_articles, search_publications, and explore_corpus, all of which target other corpora.

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?

Gives clear operational context: 'Call with no arguments to list all' and instructs to 'Use French concept keywords regardless of the user's report language.' However, it does not explicitly name alternative tools or when NOT to use this one, falling short of the top score.

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

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

Annotations already cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false), but the description adds useful non-schema context: the corpus size, the near-absence of captions, and the exact fields each result carries (image_url, coordinates, canonical page). It does not mention pagination defaults beyond the schema, but the added behavioral detail is substantial.

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: corpus identity first, matching behavior second, return fields third, usage rule last. Every sentence carries information, with only minor overlap between the keyword-matching sentence and the caption caveat.

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?

There is no output schema, so the description must describe returns — and it does (image_url, coordinates, canonical IWAC page). Combined with corpus size, caption scarcity, and the no-arg listing behavior, an agent has everything needed to call this 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?

With 89% schema description coverage the baseline is 3, but the description adds real value: it clarifies that keyword matches title/creator/subject/place/caption and warns that captions are almost never present, steering agents toward subject/place instead. That is meaningfully beyond the raw schema text, though it largely restates the schema's own field list.

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 names a specific verb+resource ('Search the IWAC photographs'), scopes the corpus (30 items: mosques, radio stations, schools, signage, street scenes) and describes the matching surface. It also distinguishes itself from the sibling alternatives (subject/place filters, semantic_search_images), so an agent can place it without opening a schema.

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 explicitly states the no-argument behavior ('Call with no arguments to list all') and gives a routing rule: prefer subject/place filters over keywords, or semantic_search_images when enabled. That is concrete when-to-use and when-to-prefer-an-alternative 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 the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description usefully adds that matching is accent/case-insensitive, a real behavioral trait not in the annotations, but says nothing about return format, pagination, or result ordering.

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 tight sentences, zero filler, with the core verb/resource and the accent/case-insensitivity caveat front-loaded. Every clause 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 4-parameter search tool with no output schema and an undocumented offset parameter, the description covers what is searched and how matching works but omits pagination behavior and how index_type interacts with the search. Adequate but with clear gaps.

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

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

Schema coverage is 75%, and the schema already documents keyword, limit, and the validated index_type values in detail. The description's 'by name' and accent-insensitivity add a little meaning to keyword matching, but offset remains undocumented in both schema and description.

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

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

States a specific verb (Search) and resource (IWAC authority index) and enumerates the entity types covered (persons, places, organisations, events, subjects), which is more specific than a bare 'search'. It does not, however, distinguish itself from close siblings like get_index_entry, list_persons, or list_subjects.

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 says it searches 'by name' but offers no when-to-use guidance, no exclusions, and no routing to alternatives. With siblings such as get_index_entry (single-entry retrieval) and list_persons/list_subjects, an agent gets no help deciding between them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context beyond them: the keyword match surface (title, subject, TOC, full OCR), that TOC hits surface as matching_toc_entries, and the French-keyword requirement. It doesn't explain result ordering or 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?

Four front-loaded sentences with little waste: purpose first, then matching semantics, then filters, then alternative tools. Dense but each sentence earns its place; slight compression possible in the keyword-matching clause.

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?

A 13-parameter tool with no output schema and no required fields leaves the agent needing more guidance. The description covers keyword semantics, filters, and the matching_toc_entries return hint, but omits keyword_mode/keyword_aliases behavior, the exact filter object's mechanics, and overall result shape or default limit/pagination.

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 77%, near the high band, so the schema does most of the work. The description adds semantic meaning for keyword (French concept, accent-insensitive substring) and filter usage (newspaper/series, subject, country, year), but leaves keyword_mode, keyword_aliases, and the nested exact object entirely to the schema.

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

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

States a specific verb and resource ('Search Islamic publications (periodical issues, books)') and scopes the corpus. It differentiates from get_publication_fulltext (single-issue excerpts) and list_periodicals (series discovery), but does not distinguish itself from the numerous other search_* siblings such as search_articles 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?

Gives concrete when-to-use guidance by naming two alternatives with their roles: list_periodicals to discover series titles and get_publication_fulltext for keyword excerpts from a single issue. It also prescribes using French concept keywords regardless of report language. It stops short of explicit exclusions against the other search_* tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior the annotations cannot convey: keyword is a substring match over title+abstract only, multilingual corpus with French metadata labels, and that results carry only a short abstract snippet.

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?

Four sentences, each load-bearing: purpose, keyword constraint, multilingual guidance, and routing to get_reference. The most important operational caveat (one term per call) is front-loaded after the purpose sentence with no filler.

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

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

With no output schema, the description usefully states what results contain (a short abstract snippet) and where to get more. For a 10-parameter, zero-required search tool it covers the high-risk semantics well, though it leaves pagination and limit/offset behavior entirely to 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?

Schema coverage is already 80%, so the baseline is 3, but the description adds real semantic value: it explains the substring/one-term-per-call constraint on `keyword` and warns that filter values such as `reference_type` and `language` use French labels. It does not touch the country/date/subject parameters beyond what the schema says.

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

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

States a specific verb (search) and resource (academic references) and enumerates the covered document types (journal articles, book chapters, theses, books, reports). It explicitly contrasts itself with get_reference, but does not differentiate from the sibling search_articles, which an agent must disambiguate on its own.

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?

Gives concrete operational guidance: search ONE term per call because combined terms miss results, and try both French and English keywords. It also names the alternative (get_reference) for the full abstract. No explicit when-not-to-use against the other search_* siblings, so it stops 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.