Islam West Africa Collection (IWAC)

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond those annotations: exact filters intersect, coverage measures archive availability, exports identify the page and dataset snapshot, and snapshot IDs can be compared 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?

The description is dense but front-loaded, starting with the workbench purpose and mode list before moving to behavioral details. It is appropriately sized for a multi-mode tool, though the telegraphic phrasing occasionally makes it harder to parse.

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

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

This is a complex tool with nested selection/comparison objects and low schema coverage, and an output schema exists so return values need not be explained. The description covers several invocation-relevant behaviors, but gaps remain around the 'link' parameter, individual filter fields, and mode defaults.

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 14%, so the description must compensate. It clarifies mode categories, limit/offset behavior for certain modes, the required comparison for compare mode, and exact-filter intersection, but it omits important semantics such as the 'link' export option and details of several selection fields.

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 identifies a specific multi-mode selection workbench and enumerates its modes (items, concordance, coverage, compare, attention, aliases, exports), giving a clear sense of what the tool does. It does not explicitly compare itself to the large set of search/get/list siblings, but the mode list distinguishes it as a broader selection and export surface.

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 some operational guidance, such as 'compare (requires comparison)' and that limit/offset page compare/coverage/attention cells. However, it does not state when to use this tool instead of search_* or get_* siblings, nor does it describe when not to use particular modes.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real value by explaining what `text` contains (OCR/abstract/transcription) and that `url` is the canonical link to cite. It doesn't mention behavior on invalid/missing ids.

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 action and no filler. The first sentence is dense and runs long with parentheticals, but every clause (id format, return shape, field meanings, categories) carries information an agent needs.

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, full annotation coverage, and a 100%-documented single parameter, the description is nearly complete: it covers sourcing the id, the return payload, and valid categories. The remaining gap is its unresolved relationship to the category-specific get_* siblings and error handling.

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

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

Schema coverage is 100% with a single well-documented `id` parameter, so baseline is 3. The description adds the full category enumeration (articles, publications, references, documents, index, audiovisual, images) and the '<category>:<number>' grammar, which goes beyond the schema's two examples.

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 ('Retrieve') and resource ('full text and metadata of one IWAC item') with the exact id format. The 'id returned from `search`' framing makes it distinguishable from the category-specific get_article/get_document/get_reference siblings.

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

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

Explicitly anchors usage to ids returned by `search`, which gives a clear workflow context. However, it never says when to prefer this generic fetcher over the category-specific siblings (get_article, get_document, get_image, etc.), leaving the main selection ambiguity unresolved.

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 safety is covered. The description adds genuinely new behavior: OCR is chunked into 25k-character parts and must be followed via next_offset, and keyword mode changes the return shape to excerpts. No info on missing-id behavior or auth.

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 waste; the primary retrieval behavior is front-loaded, and the pagination and keyword-mode details follow in priority order.

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 does the necessary work of naming the returned fields and explaining how large payloads are split. Minor gaps remain: what happens when the id doesn't exist, and whether metadata/sentiment are truncated alongside the OCR.

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% and already defines offset as the previous part's next_offset and keyword as accent-insensitive excerpt matching. The description mostly restates that; the only real additions are the 25k chunk size and the ~2000-char excerpt size, which is correct but marginal.

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?

Specific verb + resource (get one article by id) plus an enumeration of what comes back: full metadata, AI abstract (description_ai), AI sentiment, OCR text. The by-id single-record framing distinguishes it from search_articles / semantic_search_articles, which return multiple items.

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

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

Gives clear operating guidance for pagination ('follow next_offset') and a mode switch: pass `keyword` to trade full OCR for ~2000-char excerpts. It stops short of naming sibling tools (e.g., use search_articles to find an id first), so routing 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 declare this as a safe read-only, idempotent operation; the description adds valuable behavioral detail beyond that. It explains the three link types and their meanings, clarifies `source_type`, and discloses that long transcriptions are returned in 25k-character parts with `next_offset`.

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 and every clause carries useful retrieval context. The field enumeration, link distinctions, and pagination note are all relevant and efficiently packed into two sentences.

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 carries the burden of explaining return content; it does so thoroughly. It covers the record fields, the three URL variants, source-type behavior, and transcription pagination, leaving little ambiguity for an agent invoking it.

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

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

Schema coverage is only 33%, so the description must compensate. It clarifies that `keyword` returns excerpts rather than full transcription and that pagination follows `next_offset`; the required `audiovisual_id` is obvious from 'by id'. It could be more explicit about passing `offset` as the pagination parameter.

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

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

The description opens with a specific verb and resource: 'Get one audiovisual record by id.' It immediately distinguishes this retrieval-by-id operation from list/search siblings and enumerates the record content an agent can expect.

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 clear from 'by id' and from the note that `keyword` returns excerpts instead of full transcription. It also explains pagination via `next_offset`. It does not explicitly name search_audiovisual or list_audiovisual as alternatives for finding an id, so it falls short of full when-to-use 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/non-destructive, so the bar is lower. The description adds real semantic context beyond them: what fulltext_coverage means and the interpretive caveat about keyword counts. It doesn't mention cost or output shape, but the output schema covers shape.

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 waste. The core purpose is front-loaded and the caveat follows as the actionable detail.

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

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

With an output schema present and no parameters, the description only needs to justify existence and flag interpretation pitfalls — it does both. The remaining gap is the lack of explicit routing to sibling tools for different statistics.

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?

Zero parameters, so baseline 4 applies. There's nothing for the description to document and it doesn't waste space pretending otherwise.

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: 'Overall statistics for every IWAC subset', which distinguishes it from the metric-specific siblings like get_lexical_metrics and get_newspaper_stats by being the aggregate overview. It doesn't explicitly name an alternative, so it falls short of 5.

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

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

The second sentence implies when the output matters ('Read that before treating any keyword count as a full-text census'), giving a concrete decision context. However, there's no explicit when-to-use-this-vs-sibling guidance among the many search/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 establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower, yet the description adds real value: filters are applied before pair counting (an ordering guarantee that affects results) and top_n caps vocabulary size. The explicit warning that associations are descriptive, not causal, is exactly the kind of interpretive guardrail 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?

Three sentences, each doing distinct work: purpose, interpretive caveat, parameter behavior. The purpose is front-loaded and there is no filler or restatement of the tool name.

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 14 parameters, a nested object, and all-optional arguments, the description should say more about how date, keyword, and hijri filters interact with the exact/field axis. The output schema exists, so return-value explanation is rightly omitted. Adequate but with clear gaps 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 64%, so the schema documents field, top_n, subset, and the nested exact object, but leaves date_to, keyword, hijri_year, hijri_month, and keyword_aliases largely bare. The description only reinforces top_n ('caps the vocabulary') and the general filter behavior, adding little for the undocumented half. Baseline 3 is appropriate given partial coverage.

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

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

The opening clause names a specific operation on a specific resource: counting pairs of metadata values co-tagged on the same items. That is clearly distinct from distribution tools like get_field_distribution or get_semantic_map. It stops short of naming a sibling to contrast against, so a 4 rather than a 5.

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

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

The description never says when to reach for this tool versus get_field_distribution, get_semantic_map, or get_topic_distribution. The clause about matrix/network views showing descriptive rather than causal associations is an interpretive caveat about output, not usage routing. An agent must infer the use case from the purpose sentence alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds the set of aggregated dimensions but says nothing about cardinality (all countries? ranked how?), cost, or aggregation semantics. With an output schema present, return-format disclosure is rightly omitted, so the remaining gap is modest.

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?

One front-loaded sentence with no filler or repetition. The only mark against it is the opaque "claude-haiku-5-5 polarity" token, which costs comprehension without adding a full 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?

Output schema and annotations carry the return-shape and safety information, so nothing critical is missing. Still, an agent cannot tell from the text whether results cover every country, how they are ordered, or how the polarity metric differs from get_sentiment_distribution — meaningful gaps for a comparison tool priced against a large sibling set.

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 schema burden is nil and the baseline of 4 applies. Nothing in the description contradicts the empty input object.

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?

A specific verb ("Compare") plus a concrete enumeration of the metrics being compared across countries, so an agent knows exactly what the tool returns. It does not, however, distinguish itself from plausible siblings such as get_collection_stats or get_place_distribution. The term "claude-haiku-5-5 polarity" reads as an internal model label leaking into the description and blurs one of the four metrics.

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

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

There is no statement of when to use this over the many stats/distribution siblings, and no exclusion or prerequisite guidance. The only implied usage comes from the word "compare" itself. An agent must infer the scenario from the metric list alone.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are chunked into 25k-character parts with a `next_offset` continuation, and supplying a keyword changes the return shape to ~2000-char excerpts. Not stated: what happens on an invalid id or whether metadata is still returned in keyword mode.

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 primary retrieval mode before the alternate keyword mode. No filler and no repetition of annotation or schema text.

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

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

No output schema exists, and the description carries the return-value burden well by naming the three payload components and the pagination contract. It falls slightly short on failure modes and on whether excerpt mode also includes the metadata block.

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 baseline is 3; the description goes further by tying `offset` to the chaining pattern ('follow next_offset') and framing `keyword` as the long-document alternative with an approximate excerpt size. Only `document_id` and the max_excerpts/context_chars interaction remain schema-only.

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 archival document (by id)') and enumerates what comes back: full metadata, AI description, and OCR text. It does not distinguish itself from look-alike siblings such as get_article, get_image, or fetch, so an agent must infer which document type maps to which 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?

Guidance is strong within the tool — 'Pass a keyword to get ~2000-char excerpts around each match instead, useful for long documents' clearly routes between full-text and excerpt mode. However, with 39 siblings including search_documents, fetch, and get_article, there is no guidance on when to call this tool versus those alternatives.

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

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

Annotations already declare this a read-only, idempotent, closed-world operation, so the safety bar is low. The description usefully adds that pipe-separated tags are split and that missing metadata is reported, plus that coverage over time is optional via over_time. It says nothing about how 'exact' AND-filters, keyword_mode, or subset change results, leaving substantial behavioral surface undocumented for a 15-parameter tool.

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, front-loaded with the core operation before the field-selection advice. No filler or restatement of the title. Slightly compressed to the point of terseness in the final sentence.

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 needn't be explained, and annotations cover safety. But for a 15-parameter tool with a nested 'exact' object and multiple filter modes, the description omits how filtering interacts with ranking and what the coverage-over-time output looks like. 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 67%, so baseline is 3. The description clarifies that values are ranked and that tags are split on pipes, and it hints at field semantics, but it adds no meaning for 'exact' AND semantics, 'top_n' ranking basis, 'subset' scopes, or 'keyword_mode' beyond what the schema already states.

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: ranks exact metadata values from a chosen field, with pipe-separated tag splitting. It also distinguishes the 'field' choices (spatial vs country vs subject/author/language), which helps separate it from related distribution tools. It never explicitly names the sibling distribution tools it competes with, so it stops 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?

Gives conditional guidance on field selection ('spatial for mentioned places, country for stored country tags'), which is genuinely useful because those map to other tools. However it never names alternatives like get_place_distribution, get_country_comparison, or get_topic_distribution, and gives no guidance on when NOT to use this tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value with 'The server returns URLs, not image bytes', which prevents an agent from expecting binary content, and by enumerating the response fields in the absence of an output schema.

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

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

Two tight sentences with zero filler; the resource and field list come first, followed by the one operational caveat. 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?

With no output schema and no annotation detail on returns, the description appropriately enumerates what comes back and clarifies URLs vs. bytes. The remaining gap is provenance of image_id and error behavior, which an agent would want for a required single-parameter 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?

Schema description coverage is 0% and the single parameter (image_id, integer) is undocumented in the schema, so the description must carry the load. It says only 'by id' and never states the id format, its source (e.g. from a search result), or behavior for an unknown id.

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 ('one photograph by id') and enumerates the returned fields (title, photographer, capture date, coordinates, subjects, rights, IIIF manifest, image_url). It is clearly a single-record fetch, which implicitly separates it from search_images/semantic_search_images, but 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?

The phrase 'by id' implies this is the tool to call once you already have an image_id, but it never says so outright or points to search_images/semantic_search_images as the way to obtain one. No when-not-to-use guidance is given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description does add useful value beyond that: it discloses that returned fields are raw dataset columns with French labels (Titre, Prénom, Coordonnées), which sets expectations for the response shape. It says nothing about what happens for a missing/invalid id or about result size.

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?

One front-loaded sentence with the core action first and the parenthetical detail after; every clause carries information. 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 partially compensates by previewing the returned columns and their French naming. However, it omits the id's provenance, error behavior for unknown ids, and whether the entry is tied to a specific corpus/dataset — gaps an agent will hit in practice.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning, and it only says 'by id'. That identifies the key as an identifier but does not clarify type (integer), format, or where the id is obtained. Minimal compensation for a single required parameter.

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 full details of an index entry") and the lookup key (by id), which distinguishes it from the search/list siblings. It does not explicitly name search_index as its companion, but the singular 'entry' vs. search framing is clear enough to separate them.

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 statement of when to use this instead of search_index or explore_corpus, and no guidance on where a valid entry_id comes from. The agent must infer that this is a follow-up hydration call after an index search. No exclusions or prerequisites are given.

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

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

The description adds useful behavioral context beyond the annotations: metrics are precomputed, readability is French-specific and excludes other languages, and missing values are disclosed. With read-only and idempotent annotations already covering the safety profile, these limitations are exactly the kind of extra context an agent 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?

The description is compact and front-loads what metrics are returned and how they are grouped. The final sentence about comparing distributions is somewhat vague, but overall there is little wasted text.

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

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

Because an output schema exists, the description need not document return values. However, this is a complex 13-parameter tool with many sibling alternatives, and the description does not fully cover filtering semantics or selection guidance, leaving it only adequately 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 62%, so some parameter meaning is already documented. The description adds the grouping dimensions country/newspaper/year but does not explain filters such as exact, keyword aliases, date bounds, or top_n, leaving a meaningful gap at this coverage level.

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 returned resource: text length, lexical richness and readability grouped by country/newspaper/year. It does not explicitly distinguish this tool from sibling distribution and statistics tools such as get_collection_stats or get_country_comparison, so it stops short of a 5.

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

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

The phrase 'Compare distributions as descriptive evidence' gives an implied use case, but the description does not state when to choose this tool over sibling alternatives or when not to use it. Usage is therefore inferable but not explicit.

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, non-destructive and closed-world, so the safety profile is covered. The description adds that the result is an aggregate of counts plus date ranges, which is genuine behavioral context, but it says nothing about scope (whole corpus vs. filtered) or ordering of the returned newspapers.

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?

One front-loaded sentence fragment with no filler, and the key output notion is stated up front. It is efficient but borders on under-specification given a filterable, aggregating 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 described, and annotations carry the safety profile. Still missing is the optional country filter and whether the default is the whole corpus, which an agent needs in order to pick between this and get_country_comparison.

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

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

Schema coverage is 100% and the single country parameter is fully documented in the schema with its allowed values and accent tolerance. The description never mentions the country filter, adding nothing beyond the schema; baseline 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?

States the resource (per-newspaper statistics) and the two metrics returned (article counts and date ranges), which is more specific than the title alone. It does not differentiate from near-siblings such as get_collection_stats or get_country_comparison, so the agent must infer the newspaper-level granularity.

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 statement of when to use this tool, when not to, or which sibling to prefer for corpus-wide or country-level stats. The only hint that it is newspaper-level comes from the word 'per-newspaper' in the description text.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds meaningful data behavior: place tags are joined to authority coordinates, publication countries are separated from mentioned places, and missing geocodes are counted explicitly. No contradiction.

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

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

Two tight sentences with no filler. However, the first sentence is jargon-heavy and not maximally front-loaded; it is concise but could be clearer.

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?

Core conceptual behavior is present and an output schema exists, so return values need not be described. But for a 13-parameter analytical tool, missing usage guidance and filter semantics leave the definition only minimally complete.

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

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

The description mentions no parameters at all, and with 13 params at 62% schema coverage several fields such as date_to, keyword, hijri_year, hijri_month, and keyword_aliases lack descriptions. It does not explain subset, country, top_n, or filtering semantics beyond what the schema partially provides.

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

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

The description identifies the resource (place tags joined to authority coordinates) and a key data distinction, but it never states the operation explicitly—no verb like 'returns counts/distribution' and no sibling differentiation from list_locations or get_country_comparison. The name carries most of the purpose.

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

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

There is no when-to-use, when-not-to-use, or alternative tool guidance. It does not explain whether to choose this over list_locations, get_country_comparison, or get_semantic_map.

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 that this is a read-only, idempotent, non-destructive operation. The description adds useful behavior beyond annotations: 25k-character pagination via next_offset, keyword excerpts of about 2000 characters, accent-insensitive matching, and capped excerpt behavior indicated by match_count versus 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 dense sentence, front-loaded with the primary purpose and then the alternate mode. It contains no filler and every clause contributes operational 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 5-parameter retrieval tool with no output schema, the description covers the key modes, pagination flow, excerpt sizing, and result-limit concept. It is slightly incomplete because publication_id semantics and exact response field behavior are not fully explained.

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 60%, so the schema already documents offset, max_excerpts, and context_chars. The description adds meaning for keyword matching and pagination, but publication_id remains undocumented and the exact cap mechanics are only referenced indirectly.

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: retrieves full OCR text of a publication, with clear paged full-text and keyword-excerpt modes. It does not explicitly distinguish itself from sibling retrieval tools such as get_document or get_article, so it is clear but not fully sibling-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?

The description implies when each mode applies: use offset paging for full text, or keyword for excerpts around matches. However, it does not explicitly say when to use this tool versus search_publications or other retrieval siblings, nor does it state 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 behavior, so the description adds real value by warning that abstracts are present in only ~51% of records — a caveat that affects downstream planning. It also previews record shape (host-work details), but says nothing about behavior for a missing/invalid id.

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?

One dense sentence that front-loads the purpose and uses the parenthetical detail to scope the payload. No wasted framing; the parenthetical field list is slightly list-heavy but each element earns its place.

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

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

With no output schema, the description does the work of describing return contents and flags the incomplete-abstract caveat. Only gaps are not-found/error behavior, which is minor for a simple id 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?

Schema coverage is 0%, so the schema alone documents only that reference_id is a required integer. The description clarifies it is a single-reference id lookup, which is marginally useful, but does not say where ids come from (search_references results) or that the identifier is numeric.

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: returns the full bibliographic record for one academic reference by id, and enumerates the returned fields (abstract, subjects, DOI/URL, host-work). An agent can tell this is a single-item detail lookup rather than a search, though it never names the sibling search_references it complements.

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 'by id' framing implies this is the follow-up call once an id is known, and the 51% abstract note signals it is not the tool for abstract-based discovery. However, no explicit when-to-use/when-not statement or named alternative (e.g., search_references) is given.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description adds real value: deterministic stable-hash sampling, returned counts/seed/explained variance, and the caveat that coordinates are chart-only and not the published UMAP layout. It does not address the sampling cap behavior or what 'invalid/missing' mean operationally.

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 tight sentences, front-loaded with the mechanism and followed by output contents and the key caveat. Dense but every sentence carries information; minor cost from compressed phrasing like 'Group counts describe the sample.'

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

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

With an output schema present, the description needn't enumerate return fields, yet it usefully summarizes them (eligible/invalid/missing/capped, seed, explained variance). Annotations cover safety. Only gap is that filter parameters and subsetting semantics are left 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 64% across 14 parameters with a nested 'exact' object, so the schema carries most of the semantic load. The description mentions 'matching' and 'Group counts' but adds no detail on filters, limit caps, or subset/color_by behavior beyond what the schema already documents.

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 concrete mechanism: stable-hash sampling of stored embeddings projected with PCA, and explicitly names what it is not ('not the published UMAP landscape'). An agent can tell this apart from semantic_search_* siblings, though the phrase 'semantic map' itself remains loosely defined.

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 rather than stated: 'Coordinates are chart-only' signals a visualization/exploration use case, and 'Needs no API key' removes a barrier. There is no explicit when-to-use-this-vs-semantic_search_articles guidance or statement of exclusions beyond the UMAP disclaimer.

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 read-only, idempotent, non-destructive profile, so the description's job is to add analytical context — and it does: labels are model interpretations not ground truth, subjectivity is weak evidence, and its caveat must accompany findings, plus kappa denominators are reported explicitly. This is substantive epistemic context an agent cannot get from 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 dense sentences, front-loaded with the core action and then the mode selection, with no filler. Some phrasing is heavily compressed jargon ("explicit denominators"), 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?

With an output schema present, return-shape explanation is unnecessary, and the description covers the non-obvious parts: mode switching, pairwise agreement statistics, and the interpretive caveat. It stops short of explaining how the filter set combines (AND semantics in `exact`) or default model behavior, which matters for a 14-parameter 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?

At 57% schema coverage across 14 parameters, some compensation is required: the description meaningfully explains model:"all"/"consensus" semantics and the purpose of compare_models and agreement_field (pairwise Cohen's and quadratic weighted kappa). But it says nothing about the many filter parameters (exact, keyword_mode, hijri_year, date bounds) or the dependency that agreement_field presumably requires compare_models.

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 — aggregating AI labels (polarity/centrality/subjectivity) over a shared selection — and names the two special modes ("all", "consensus") that make this tool distinctive. However, it never explicitly distinguishes itself from close siblings such as get_field_distribution or search_by_sentiment, so an agent must infer 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?

It gives real internal-mode guidance: model:"all" for independent annotators vs "consensus" for the stored panel majority, and when to reach for compare_models plus agreement_field. What it lacks is tool-level guidance — no statement of when to call this instead of get_field_distribution, get_topic_distribution, or search_by_sentiment.

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

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

Beyond the read-only and idempotent annotations, the description explains score behavior in detail: unrelated items score around 0.7, scores of at least 0.97 suggest near-duplicates, and no threshold proves a reprint. It also notes that articles and documents lead with a published top 10 and that results include source IDs and dates.

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

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

The description is compact and front-loaded: it leads with the core operation, then gives score semantics and scope limits. Every sentence adds useful information without repetition.

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

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

Given the 100% schema coverage, read-only annotations, and an output schema, the remaining description covers the important behavioral nuances: score interpretation, near-duplicate caveat, default published top 10 context for some subsets, and the offline boundary for corpus-wide work.

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

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

Schema coverage is 100%, so the schema already documents id, limit, subset, and min_score. The description adds meaningful interpretation for min_score by explaining that high cosine similarities are common and that 0.97 suggests near-duplication, which is more than the bare schema range.

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 first sentence states a specific retrieval operation: nearest stored embeddings by cosine similarity. It implies item-based similarity rather than query-based search, but it does not explicitly name a sibling alternative or state that it operates from a given item id in the description itself.

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

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

The description gives a clear exclusion: 'Corpus-wide candidate generation belongs offline.' That helps an agent avoid using it for bulk candidate generation, but it does not explicitly name which sibling tool to use for query-based or corpus-wide search.

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-only, idempotent profile, yet the description still adds real behavior: partial dates and missing lunar dates are disclosed (a data-quality caveat), normalize_by returns both numerators and per-bucket denominators, and thematic filters are dropped from the denominator. The closing note that shares describe IWAC holdings, not the filtered subset, is exactly the kind of interpretive context 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 short, front-loaded sentences that lead with the core computation before caveats and normalization. Telelegraphese ('Shares describe IWAC holdings') is terse 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?

With an output schema and rich annotations handling return shape and safety, the description fills the remaining gaps an agent needs: bucket definitions, grouping, data-gap disclosure, and the denominator semantics of normalization. Nothing essential to correct invocation appears 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?

With 16 parameters and 69% schema coverage, the schema does most of the work. The description reinforces the meaning of calendar, granularity, group_by and normalize_by beyond the schema text, but leaves hijri_year/hijri_month, keyword_mode, keyword_aliases and the nested exact filter undocumented.

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 computation: counts bucketed by Gregorian or Hijri year/month or pooled lunar month, with optional grouping by country/newspaper. That clearly separates it from get_topic_distribution, get_field_distribution or get_cooccurrence by virtue of being temporal, 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?

Use is implied by the bucketing options and the grouping clause, but there is no explicit statement of when this tool should be chosen over the other distribution tools, nor any stated prerequisite (e.g. calendar=hijri is required for granularity=lunar_month is only in the schema).

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 read-only/idempotent/non-destructive, so the description's job is to add data-semantics context, and it does: topic labels are interpretive model outputs (a quality caveat), topic_id filtering operates on assignments not text matches, and results report unclassified coverage. It stops short of describing ordering, defaults, or how subset=references changes output.

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 operation before caveats. No filler, though 'Reports unclassified coverage' is terse enough to be slightly ambiguous about whether it is a flag, a count, or a separate section.

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 tool with nested `exact` and an output schema, the description covers purpose and the most surprising semantics but omits how results are grouped/ordered, what subset=references does, and the relationship between top_n and over_time. 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 67%, so the schema carries most parameter documentation. The description adds real meaning for topic_id (exact assignment selection vs keyword match) and implies over_time/top_n behavior, but leaves other parameters like subset, keyword_aliases, and hijri_year unaddressed.

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 ('Counts of offline LDA topic assignments') plus an explicit scope modifier ('optionally over time'). An agent can distinguish it from get_temporal_distribution and get_field_distribution by the LDA-topic subject, though no sibling is named directly.

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 statement of when to prefer this over get_field_distribution, get_temporal_distribution, or get_cooccurrence, and no prerequisites. The note that 'exact topic_id filters select assignments rather than keyword matches' clarifies filter behavior but is not usage 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, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value beyond that with the 'newest first' ordering guarantee and a concrete characterization of the corpus (francophone web video vs. deposited Nigerian recordings), which an agent cannot infer from annotations or 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?

Two sentences with the ordering and filter affordances front-loaded; no filler. The parenthetical corpus sketch is dense but earns its place by telling the agent what content is actually reachable.

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

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

With no output schema and zero required parameters, the description supplies the essentials: what is listed, in what order, and which dimensions can be filtered. Pagination behavior (default 20, max 50) lives in the schema, so its absence from the description is not a real 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 coverage is 80%, so the schema already documents limit, offset, country, publisher and source_type thoroughly, including the country enumeration and source_type values. The description names three of the five filters but adds no syntax, matching behavior, or format detail beyond what the schema states, so the baseline 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 gives a specific verb and resource ('List audiovisual materials') plus an ordering guarantee ('newest first') and the corpus scope it covers. It implicitly separates itself from get_audiovisual (single item) and search_audiovisual (keyword search) by presenting itself as a filtered enumeration, 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?

Usage is only implied: 'Filter by country, publishing channel or source_type' suggests this is the browse-and-narrow tool, but there is no explicit statement of when to prefer it over search_audiovisual or explore_corpus. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds context the annotations cannot: the sort key and ranking definition, the fact that 'frequency' counts articles/publications/references rather than place occurrences, and the data-coverage caveat that no article is Nigerian — these materially shape interpretation of results.

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

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

Purpose is front-loaded in the first clause, followed by the important caveat, and every sentence earns its place. There is mild redundancy: the 'mentioned-in, not located-in' point is made twice and largely duplicates the country parameter's schema text.

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

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

For a read-only, zero-required-parameter list tool with an output-less schema, this covers what an agent needs: what is listed, how it is ordered, and how the filter behaves counterintuitively. Minor gaps remain around tie-breaking within equal frequencies and the shape of individual entries.

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?

At 67% schema coverage the schema already documents limit and country well; offset is undocumented in both places. The description reinforces and sharpens the country parameter's semantics ('APPEAR IN' vs 'located in') in a way that matters for result interpretation, though it adds nothing about offset or how limit interacts with ranking.

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 default ordering ('sorted by frequency, most-referenced first'), which is more than a restatement of the name. However, 'lieux' is domain jargon left undefined, and differentiation from near-siblings like search_index, list_persons and get_place_distribution is only implicit through the absence of a query parameter.

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 strong situational guidance for the tricky part: the country filter is scoped as 'mentioned-in, not located-in' and readers are warned that foreign/cross-border entries appear and that Nigeria returns very few results. It stops short of naming when to pick this over search_index or get_place_distribution, so the routing guidance is incomplete rather than explicit.

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 bar is lower; the description adds real value by disclosing the return payload shape (issue counts, year ranges) and the intended use of a specific returned field. It does not state what happens when `country` is omitted or whether results are paginated/ordered.

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 waste, with the resource scope front-loaded and the mechanical follow-up instruction second. Nothing is repeated from the title.

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-value detail is not required, yet the description still summarizes it helpfully. The only meaningful gap is the optional-parameter behavior: `country` is not required, and the description never says the tool returns titles across all countries when it is omitted.

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

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

Schema coverage is 100% with a single parameter whose enum-like values and accent handling are fully documented in the schema. The description adds no extra meaning about `country` (e.g., default behavior when unset), so it merely matches the schema baseline.

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?

Specific verb ("List") plus a narrowly scoped resource ("Islamic periodical/series titles in the publications subset"), and it names what comes back (issue counts, year ranges). This is clearly distinguishable from search_publications, which it explicitly designates as the downstream consumer of the returned value.

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 second sentence gives a concrete chaining instruction — feed the returned `newspaper` value into search_publications — which effectively tells the agent the situation this tool is for. It stops short of stating exclusions (e.g., when to use explore_corpus or get_newspaper_stats instead) or what the unfiltered call returns.

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 safety is covered; the description goes beyond them by defining how 'frequency' is computed (articles, publications, references) and warning that country filtering surfaces cross-border mentions. It does not disclose what a result entry contains or how paging interacts with the frequency ranking.

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 sort order are front-loaded in the first clause, which is correct. The second sentence is heavily nested (parentheticals, em-dashes, semicolons) and could be split, but every element carries information rather than 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 should say more about the returned entry shape; it explains ordering and frequency but not what fields a person record exposes. For a 3-parameter read-only list with full annotation coverage, the remaining gap is modest but real.

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?

At 67% schema coverage, the description adds net-new meaning for 'country' — the consequence of mention-based selection and the Nigeria edge case — rather than merely restating the schema. The frequency-ranking explanation also implicitly justifies limit/offset ordering, though 'offset' is never addressed in either place.

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 personnes from the IWAC index') plus the ordering ('sorted by frequency, most-referenced first'), which an agent can distinguish from siblings like list_locations or search_index. It never explicitly names a sibling to contrast against, so differentiation is inferential rather than stated.

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 spends its guidance budget on one thing: how the 'country' filter behaves (mentioned-in, not located-in) and the resulting caveat that foreign/cross-border entries appear and Nigeria yields few results. That is genuine usage guidance for that parameter, but there is no guidance on when to choose this over search_index, get_index_entry, list_locations, or how to page through results.

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, closed-world and non-destructive, so the safety profile is covered. The description adds the deterministic frequency ordering, which is genuinely useful behavior, but says nothing about pagination semantics, total counts, or what fields a sujet entry carries.

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 resource first and the sort behavior second; every clause carries information and there is 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 simple, read-only, two-parameter list tool with annotations covering safety and no output schema, the description is nearly sufficient. The remaining gap is the return shape (does each sujet include a reference count?) and paging behavior, which an agent browsing a potentially large index would want to know.

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 50%: limit is documented inline ('Default 50, max 200') but offset is completely bare. The description adds no parameter guidance at all — no default, no cap, no mention of paging through results — so the undocumented offset is left entirely to guesswork.

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 sujets from the IWAC index') plus the ordering rule ('sorted by frequency, most-referenced first'), so the agent knows exactly what comes back and in what order. It does not, however, distinguish itself from the many sibling list_* tools (list_persons, list_locations, list_periodicals), leaving the agent to infer that 'sujets' is a distinct index facet.

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: the frequency sort signals 'browse the most-referenced subjects', which hints at exploratory use. There is no explicit when-to-use statement and no mention of alternatives such as search_index or get_index_entry, which are the obvious siblings for looking up a specific subject.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral detail beyond them: accent- and case-insensitive matching, conjunctive multi-word semantics, the {results, ranking} shape, and the category/ranking fields. It stops short of stating result caps behavior or latency, but for a read-only search tool that is a minor gap.

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

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

Purpose and the one-concept rule are front-loaded, and nearly every sentence carries operational value. The language/transliteration block is slightly verbose and repeats the French-instruction idea, so it is helpful but not maximally tight.

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?

Covers retrieval scope, query construction rules, language conventions, return structure (despite an output schema existing), and the follow-up tool. Nothing an agent needs to call this correctly 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?

Schema coverage is 100%, so baseline is 3, but the description goes far beyond: it dictates French query language for primary sources, French+English for references, French transliteration conventions (Tabaski, charia, Maouloud), and single-concept phrasing. That is directly actionable semantics the schema does not convey.

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) plus the exact corpus and enumerates the subsets covered (articles, publications, archives, references, audiovisual, photos, index). It also disambiguates from the search_* siblings by scope, so an agent can distinguish it from search_articles or search_index 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?

Explicitly instructs to pass ONE concept and explains why (multi-word queries AND all terms), names the alternative for filtered use ('For filtered queries ... use the search_* tools instead'), and describes the fetch handoff by id. When-to-use, when-not-to-use, and alternatives are all present.

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/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: which fields are indexed for matching and that matching is accent- and case-insensitive, which directly affects how an agent should phrase queries.

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 dense sentences, no filler, with the resource and searchable fields front-loaded and the query-language advice placed last where it is most actionable. 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 14-parameter, nested-object search tool with no output schema, the description covers the searchable axes and the matching rules, which is enough to construct a correct call. It is silent on what a result row contains and on pagination behavior (limit/offset semantics live only in the schema), a minor residual 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?

At 71% schema coverage the baseline is 3, but the description adds meaning the schema only partially carries: the keyword semantics (every word must occur, any order, across title/OCR/abstracts) and the French-preference rationale. It does not, however, clarify the `keyword_mode` enum, whose `all_terms` value is 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 and resource ("Search IWAC newspaper articles") and enumerates the filterable axes: keyword, country, newspaper, subject, date range, plus which text fields the keyword hits (title, OCR, French/English AI abstracts). It does not explicitly name sibling search tools such as semantic_search_articles or search_publications, so an agent must infer the lexical-vs-semantic split itself.

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 guidance sentence — "Use French concept keywords regardless of the user's report language" — is genuinely useful query-formulation advice. However, it says nothing about when to choose this tool over semantic_search_articles or explore_corpus, and sets no exclusions or prerequisites.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the description doesn't need to repeat safety. It does add real behavioral value: every row carries `source_type` and exactly one of `external_url` (stream) or `media_url` (file), never both — a non-obvious invariant an agent must know to interpret results. It doesn't cover ordering, ranking or pagination limits, which keeps it off 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?

Three sentences, each earning its place: purpose and corpus scope first, match semantics second, row shape last. The parenthetical about item descriptions being 'the richest text most of these items have' is a useful justification for keyword behavior, not padding.

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?

Nine optional parameters with no output schema, and the description covers both what the corpus contains and what a returned row looks like, which is the main gap elsewhere. What's absent is result ordering/ranking and how limit/offset behave across a full result set — minor but relevant for a search tool an agent may page through.

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 89%, so per-field syntax is already documented. The description still adds meaning beyond it by enumerating precisely which fields a `keyword` matches (title, creator, publisher, subject, spatial, language, source, item description and transcription), which the schema only calls 'title/metadata fields'. That enumeration clarifies matching behavior rather than restating parameter definitions.

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 (audiovisual materials), then names the exact scope: francophone web video from Burkina Faso, Togo and Benin plus deposited Nigerian Hausa/Arabic recordings. That scope definition is what separates it from list_audiovisual, get_audiovisual and the generic search sibling, so an agent can pick 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?

Usage is implied by the material description (which corpora it covers, what keyword matches), and the schema hints at filter choice (prefer publisher/keyword over subject). But the description never states when to choose this over list_audiovisual or the generic search, nor any exclusions or prerequisites. Adequate context, no routing 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 establish readOnly/idempotent/non-destructive safe reads, so the description is free to add the genuinely non-obvious behaviour: results reflect a single model (claude-haiku-5-5), five other models disagree, and matching is accent/case-insensitive. The caveat that the subjectivity scale is the weakest of three and produces leads rather than findings is exactly the kind of trait 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?

Three sentences, all front-loaded on the action, with the model-disagreement caveat before the scale caveat — a sensible priority order. Density is high but nothing is filler; the model identifier quote is the only slightly bumpy patch.

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 an 8-parameter, no-output-schema read tool, the description covers the interpretation risks an agent most needs (single-model bias, weak scale) and the matching semantics. It stops short of saying what a result row contains or how limit/offset paginate, which matters somewhat given there is no output schema to fall back on.

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

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

Schema coverage is 75%, so the baseline is 3 and the description only needs to add value. It does add two genuinely non-schema details — accent/case-insensitive matching and the reliability caveat on `subjectivity` — but leaves `subject`, `limit`, and `offset` untouched and doesn't explain how the three sentiment facets combine (AND vs. independent).

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+facet: 'Filter articles by ... sentiment labels', so the agent knows exactly what class of operation this is. It does not contrast itself with the near-neighbour 'search_articles' / 'search' (which could plausibly also carry filters), so the differentiation from siblings is only partial — it names get_sentiment_distribution, but for a different question (distribution vs. selection).

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 a concrete routing rule: to see how much models disagree, use get_sentiment_distribution with model:"all" instead. It also tells the agent how to treat results from the subjectivity filter ('a lead to read rather than a finding'), which is real usage guidance. What's missing is any statement of when NOT to use this tool (e.g. vs. generic article search).

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, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the corpus is tiny (~26 items), most records have OCR text plus an AI-generated description, and the indexed language differs from the user's. These details materially change how an agent queries.

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 a distinct operational fact (corpus scope, keyword language, no-arg behavior), with the most load-bearing detail (subset size) front-loaded. No filler or restatement of the tool name.

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 should say enough about what comes back; it covers scale and record enrichment (OCR, AI description) but not the result shape or pagination semantics, which matter at limit 15 / max 50 over a 26-item corpus — offset is effectively unusable and that isn't flagged.

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

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

Schema coverage is 75%, so country/limit/keyword are mostly documented already. The description's contribution is the language rule — French concept keywords regardless of user language — which the keyword schema field does not state and which an agent would otherwise get wrong on an English-speaking user's request.

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?

Specific verb plus a tightly scoped resource: a ~26-item archival-documents subset with named content types (Islamic association reports, flyers, project documents) and geography. That scope statement is what separates it from the many sibling search_* tools, though it never names a sibling directly.

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 two concrete usage rules — use French concept keywords, and call with no arguments to list everything — which is real guidance. But it never says when to choose this over search_articles, search_publications, search_index or semantic_search_*, which is the harder routing decision given 40+ siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the collection's small size, the return payload (image_url, coordinates, canonical page), and the caption-scarcity caveat that affects result quality. It stops short of describing pagination defaults or match-ordering, which keeps it below 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?

Four sentences, each carrying distinct information: scope, matching fields, return shape, and the filtering/alternative recommendation. Front-loaded with what the tool searches, with no repetition of schema-declared details.

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

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

No output schema exists, yet the description enumerates the key returned fields (image_url, coordinates, canonical page) and warns about sparse captions, so an agent knows what comes back and what limits recall. Combined with the 9 documented params, nothing essential is missing for correct invocation.

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 89%, so the schema already documents most parameters, setting the baseline at 3. The description contributes the matching scope of keyword (title, creator, subject, place, caption) and steers agents away from keyword toward subject/place, which is a modest but genuine addition over 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?

States a specific verb and resource ('Search the IWAC photographs'), quantifies the corpus (30 items) and enumerates its content types. It also implicitly separates itself from get_image (full record fetch) and semantic_search_images (embedding search) by describing keyword matching semantics.

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

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

Explicitly says 'Call with no arguments to list all' and names a sibling alternative: 'semantic_search_images when it is enabled'. It also gives a concrete selection rule between filter types — prefer subject/place over keyword because captions are almost never present.

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 that this is a safe, idempotent, read-only, closed-world operation, so safety behavior needs no repetition. The description usefully adds that matching is accent- and case-insensitive, but says nothing about result ordering, pagination behavior, or what a search returns.

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 written sentences with the core purpose front-loaded and the matching behavior appended. Nothing is redundant or 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?

The tool is a simple read-only search, and annotations plus schema cover most selection needs. However, with no output schema, the description never indicates what a match looks like or how results relate to get_index_entry, leaving a meaningful gap for an agent planning the call.

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%, with keyword, limit, and index_type documented but offset left bare. The description adds only the accent/case-insensitivity note, which reinforces keyword behavior, and does not compensate for the undocumented offset parameter.

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 the IWAC authority index") and lists the entity types covered, which clearly distinguishes it from generic corpus/document search tools. It stops short of explicitly naming the closest sibling, get_index_entry, or contrasting with list_persons/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?

No guidance on when to choose this over siblings such as get_index_entry, list_persons, list_subjects, or the general search tool. The phrase "by name" hints at lookup use, but there are no exclusions or alternative routing instructions.

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 still adds real behavior by disclosing that keyword matches span title, subject, TOC and full OCR text, and that TOC hits surface as matching_toc_entries. It does not discuss pagination behavior or result ordering, which limits it to a 4.

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 sentences, front-loaded with purpose then search semantics then alternatives; no filler. The parenthetical about matching_toc_entries is somewhat embedded and could have been surfaced more cleanly, 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, read-only search with a rich schema and no output schema, the description covers the mental model an agent needs: what is searched, what can be filtered, and which tools to chain. Gaps are the pagination/date semantics and the nested `exact` filter, both documented in the schema instead.

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 85%, so the baseline is 3; the description earns an extra point by explaining what `keyword` actually searches across and that any newspaper/series, subject, country and year filters combine. The nested `exact` object and keyword_mode/keyword_aliases interplay are left 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") and immediately narrows the corpus to "periodical issues, books", which separates it from search_articles, search_documents and search_images in the sibling list. An agent can pick this tool without opening any 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?

Explicitly routes the agent to list_periodicals for series discovery and get_publication_fulltext for excerpts from a single issue, and gives a working rule ("use French concept keywords regardless of the user's report language"). It stops short of saying when to prefer the semantic_search_publications sibling, which is the one obvious alternative left unaddressed.

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 behavior, so safety is covered. The description adds real behavioral context beyond that: keyword is conjunctive across title + abstract, metadata/filter values use French labels, results truncate abstracts to a snippet, and the corpus is multilingual. Missing only rate/limit behavior (limit is left to the schema).

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

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

Front-loaded with the verb and resource, then progressively more operational detail. Every sentence carries information (matching semantics, multilingual advice, result truncation, next-step tool), though the density of parenthetical hints makes it slightly cramped.

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 10-parameter, no-required-parameter search tool with no output schema, the description covers the matching model, language pitfalls, result shape (snippet), and the follow-up tool for full records. Pagination defaults and the sparse subject tag live in the schema, so the remaining gaps are minor.

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

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

With 80% schema coverage the baseline is 3, and the description earns above that by clarifying the AND semantics of keyword, the quoting convention for phrases, and the important non-obvious fact that reference_type and language take French labels. It doesn't restate the country/date filters, which the schema already documents well.

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 resource types covered (journal articles, book chapters, theses, books, reports). It clearly delimits the search mechanism to keyword matching on title + abstract, which separates it from the many get_* siblings, though it does not explicitly name search_articles or semantic_search_references as the alternatives.

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 directional guidance: try French and English keywords when relevant, use 'quote' for phrases, and use get_reference instead when the full abstract or bibliographic detail is needed. Clear usage context, but it never states when to prefer this over semantic_search_references or search_articles, so the sibling routing is incomplete.

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

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

Adds substantial context beyond the annotations: the model (EmbeddingGemma 2) runs locally with no API key, first use downloads ~350 MB (a real latency/first-call cost the agent should anticipate), OCR-unavailable articles are included (coverage envelope), and similarity_score is only comparable within a single query. That last point is a critical interpretation caveat that no annotation or schema conveys.

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, each carrying distinct load: scope, language, execution/dependency, and result-interpretation. The most consequential caveat (similarity_score cross-query incomparability) is placed last, after the agent knows what the tool is, and nothing is repeated from the schema.

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 does well to name similarity_score and its interpretation limit. It leaves gaps for a 6-parameter tool: no sense of result shape, whether filters are applied pre- or post-retrieval, or what happens when nothing semantically matches. Strong but not exhaustive for a search tool with no declared return structure.

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

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

Schema description coverage is 83%, so the schema already documents query, limit, country, dates and newspaper — baseline 3 applies. The description adds only "any language" for the query, which the schema already states, and says nothing about how country/date/newspaper interact with semantic ranking or about the max-from-default relationship for limit.

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 and scope: semantic search over title + full text, including OCR-unavailable articles. This implicitly separates it from the lexical `search_articles` and from `semantic_search_images`/`semantic_search_publications`, but it never names those siblings or says explicitly that this is the semantic (not keyword) counterpart for articles. A competent agent can infer the distinction, so 4 rather than 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?

"Query in any language" gives real context about acceptable input, and the presence of country/date/newspaper params implies filterable browsing. However there is no explicit when-to-use-this-vs-`search_articles` guidance, no statement that semantic search suits conceptual/fuzzy queries while lexical suits exact terms, and no note about when the local model download cost is worth paying. Usage is implied, not 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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds operationally significant facts the annotations cannot convey: the model runs locally with no API key, first use downloads ~350 MB, and similarity_score is only comparable within a single query. The last point is a real caveat about result interpretation that an agent would otherwise get wrong.

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 core action and mechanism, then layers on the practical details an agent needs. Four dense sentences with little waste, though the parenthetical '2 of the 30 images' statistic is more color than load-bearing.

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, and the description compensates by explaining the one return field that matters (similarity_score and its within-query-only scope), plus cold-start latency and offline operation. For a three-parameter read tool with full annotation coverage, nothing needed to call it correctly 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?

Schema description coverage is 100%, so query, limit, and country are all already documented, and the description adds only illustrative query examples rather than new semantics. It says nothing about limit defaults or country filtering behavior, so the schema does the heavy lifting and baseline 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?

States a specific verb and resource ('Find photographs by describing what they SHOW') and immediately qualifies the retrieval mechanism as cross-modal against an image embedding rather than a caption. That distinction is exactly what separates it from keyword-based siblings like search_images or search_audiovisual, even without naming them.

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 context for when this is the right tool: visual-content queries, in any language, and it explains why it succeeds where caption-based search would fail (only 2 of 30 images have captions). It does not explicitly name an alternative or state exclusions (e.g., 'use search_images for metadata filters'), 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.

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

Beyond the read-only/idempotent annotations, the description discloses that rows show only the first 600 characters, that the local EmbeddingGemma 2 model is used with no API key and an initial ~350 MB download, and that similarity_score is only comparable within one query. These are exactly the behavioral details an agent needs before calling.

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

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

The description is compact and front-loads the key scope line before coverage caveats, truncation behavior, runtime details, and score caveat. Every sentence adds actionable information, and the parenthetical details are dense but 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?

With no output schema but with complete annotations and full schema coverage, the description fills the remaining gaps: corpus coverage, sibling alternative, truncated row display, local model behavior, and score comparability. Nothing important for correct invocation 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?

Schema description coverage is 100%, so the schema already explains query, limit, and country semantics. The description adds only marginal parameter context such as querying in any language, which is already present in the schema, so the baseline 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 states a specific verb and resource: semantic search over publication tables of contents. It immediately distinguishes this from the lexical sibling by saying to use search_publications for the rest, and it names the exact coverage limitation.

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 tells the agent when this tool is applicable: only the ~40% of issues that have table-of-contents data, with none for An-Nasr Vendredi. It also names the alternative search_publications for the remaining cases, leaving no routing ambiguity.

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

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

Annotations already declare readOnly/idempotent/no-open-world, but the description adds non-obvious operational context the annotations cannot: a local model run, a ~350 MB first-use download cost, and the fact that similarity_score is not comparable across queries. These are exactly the behaviors an agent needs before invoking.

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, each carrying distinct information: capability, coverage limit + alternative, runtime/download cost, score interpretation caveat. The core capability and the sibling fork are front-loaded 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?

For a 7-parameter read-only search with no output schema, the description covers the things the structured data cannot: corpus coverage gaps, first-use latency/download, and how to interpret similarity_score. An agent can decide between this and search_references and set expectations correctly.

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

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

Schema description coverage is 100%, so the schema already documents all seven filters, setting the baseline at 3. The description adds genuine value by clarifying what the free-text query is matched against (title + abstract) and that query language is unrestricted, which shapes how the agent formulates the query.

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

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

States a specific verb and resource ("Semantic search over academic references"), plus the indexed fields (title + abstract) and language scope. It is immediately distinguishable from search_references, which the description names as the lexical counterpart.

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

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

Explicitly routes the agent: this tool covers only the ~50% of references with abstracts, and search_references must be used for the rest. That is a concrete when/when-not rule naming the alternative, not implied usage.

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