AMIRA — Africa Multiple Research Data

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: it discloses that transcripts and PDF full text are omitted by default, that metadata flags (has_transcript/transcript_length, has_fulltext/fulltext_length) signal availability, and precisely how the returned window is computed. That is exactly the kind of non-obvious behavioral detail 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?

Purpose is front-loaded and every sentence carries information about return shape or pagination with no filler. It is a dense paragraph, and the pagination sentence is demanding to parse, 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 an 8-parameter read tool with default-suppressed large fields, the description covers the return shape, the omission-by-default behavior, the enabling flags, and the paging protocol. Even with an output schema present, the pagination contract would otherwise be ambiguous, and it is fully specified here.

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 baseline is 3, but the description adds genuine derivation semantics the schema lacks: the interaction between include_* flags, the offset/max_chars pair, how the window is sized against the metadata header, and the offset + *_returned_chars pagination rule. This is real added meaning rather than restating field docs.

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 ('Retrieve one AMIRA record') and immediately constrains the input source ('by an `id` from the search tool'). This clearly distinguishes it from the typed get_* siblings, since the agent knows this is the generic id-based fetch rather than a per-type getter.

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 tells the agent where the required `id` comes from (the search tool) and explains the opt-in workflow for large payloads, which is actionable context. However, it never names an alternative tool or states when to prefer get_research_item/get_video/get_podcast over this generic fetch, so the routing guidance is implicit 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?

Goes well beyond the readOnly/idempotent annotations by enumerating what comes back (matched-item count, ranked projects, sections, subjects, people, countries, formats, sample items, the seed's amira_url), disclosing the `matching` echo field, and warning that `matched_items` counts ITEMS rather than headings. With no output schema, this disclosure is exactly the burden the description must carry.

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 dense but well-ordered paragraph: purpose first, then return contents, then the matching/count caveats. Every clause carries information, though the return-value enumeration makes it longer than strictly necessary for a single-sentence read.

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 three-parameter discovery tool with no output schema, the description covers inputs, traversal semantics, and the shape of the response, including the subtle counting distinction an agent would otherwise get wrong. Nothing material 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 the baseline is 3; the description adds value by tying entity_type values to behavior ('subject and person seeds also pivot into the cluster bibliography', 'tags are merged into subjects — there is no tag pivot'). It does not add further syntax detail for value or 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 and resource ('given one entity, find what it connects to through the research items that mention it') and names the traversal mechanism (cross-entity discovery via co-occurrence). It also distinguishes itself from the closest sibling by contrasting its item count with list_subjects' heading count.

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 use cases in the user's own phrasing ('what subjects/people/places co-occur with X?') and a second scenario (tracing a theme across projects), plus an explicit contrast with list_subjects. It stops short of stating when NOT to use it or naming a full alternative for other query shapes.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the exact dimensions of the returned data (counts, breakdowns, date range, snapshot freshness) and that it takes no arguments, so an agent knows it is a cheap, deterministic first call.

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 sentence, front-loaded with the imperative 'START HERE,' and every clause enumerates a concrete thing the overview returns. The long parenthetical list is dense but each entry earns its place by telling the agent what is available.

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 full burden of describing return values, and it does so thoroughly (corpus counts, breakdowns by university/section/type/language, date range, snapshot freshness). For a zero-argument orientation tool, nothing an agent needs 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?

Zero parameters, so the baseline is 4. The description confirms this explicitly with 'Takes no arguments,' leaving no ambiguity about invocation.

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 overview / counts) and resource (the collection), and enumerates exactly what the overview covers. The 'START HERE' framing makes it immediately distinguishable from the sibling search/list tools 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 prescribes when to use it: start here to scope the collection before drilling in with the search/list tools. It names the alternative category but doesn't name a specific sibling or state a when-not condition, so it falls just short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real value: a 50-item cap with total reported, conditional coordinates, and the { error } behavior for names outside the authority list. It stops short of auth or rate-limit context, but the truncation and failure semantics are genuinely informative.

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 operation and its key, then a compact enumeration of what is returned, then the failure case. Two sentences, no filler, every clause 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 no output schema, the description carries the return-shape burden and does so: projects, research items (with the cap and total), people, coordinates, and a citable URL. Combined with the documented error case, an agent has everything needed to call and interpret 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?

Single parameter with 100% schema coverage gives a baseline of 4. The description technically adds the case-insensitive matching rule and the authority-list constraint, which the schema's bare 'Institution name' does not convey, so it slightly exceeds the baseline rather than merely repeating it.

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: 'Detail for one institution (or group) by `name`'. The singular 'one institution' contrasts naturally with the plural listing sibling (list_institutions), so the agent can tell lookup from enumeration. It also names the input key and its case-insensitivity.

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

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

Usage is implied (call it when you have an institution name and want detail), but there is no explicit when-to-use/when-not or stated alternative such as list_institutions. The note that the name must appear in the organisation authority list is a useful implicit prerequisite, but it is framed as a return condition rather than 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 cover the read-only/idempotent/non-destructive profile, yet the description adds real behavioral context the annotations cannot: research items are capped at 50 with the total reported (truncation semantics), empty lists mean the name appears nowhere, the canonical 'Surname, Forename' form is echoed back, and a citable amira_url is returned. These are exactly the edge cases 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 opening clause is front-loaded with the core purpose, and the enumerated facets are dense but purposeful. The trailing edge-case sentence also earns its place; slightly compressed, but no filler.

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

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

With no output schema, the description carries the return-value burden and does so well, describing the returned facets, truncation behavior, canonical name echo, and the URL. For a one-parameter read tool with full schema coverage, nothing an agent needs 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 the single 'name' parameter is already fully documented in the schema (ordering and accents). The description's remarks about canonical spelling are about the return value rather than the input parameter, so there is little added parameter meaning beyond 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?

The description names a specific verb and resource ('Aggregate everything the collection knows about one person') and enumerates the aggregated facets (affiliations, projects, research items, publications), which clearly sets it apart from the singular get_* tools. It stops short of explicitly contrasting itself with the sibling search_persons tool, which is the one an agent might confuse it with.

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 through the 'Aggregate everything... about one person' framing, and one useful edge-case hint is given ('Works even for names absent from the authority list'). However, there is no explicit when-to-use guidance or steering between this and search_persons when the caller only has a partial or ambiguous name.

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, yet the description still adds real behavioral context beyond them: the transcript is omitted by default with only has_transcript and transcript_length shown, paging is required for long transcripts, and an { error } is returned for an unknown 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?

Two dense sentences with no filler; the core scope and the key default (transcript omitted) are front-loaded. The field enumeration is long but earns its place because there is no output schema to describe return values.

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

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

With no output schema, the description carries the full return-value burden and does so by listing the fields returned, the date_status states, the transcript default, and the error case. An agent has everything needed to call it correctly and interpret the result.

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 baseline is 3, but the description adds meaning by tying the three transcript parameters together (default omission, include_transcript=true, and paging a long transcript). This clarifies how the parameters interoperate beyond the individual schema descriptions.

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

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

The description states a specific verb and resource ('Full detail for one podcast episode') and enumerates the returned fields, so the agent knows exactly what it retrieves. The only gap is that it never names search_podcasts as the contrasting sibling, so sibling differentiation is implied rather than explicit.

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 useful mechanics for the transcript ('OMITTED by default ... pass include_transcript=true and page a long one'), which guides how to call the tool. However, it never states when to prefer this over search_podcasts or when not to use it, so tool-selection guidance is only implied.

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

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

Annotations already declare it as a safe read (readOnlyHint, idempotentHint, destructiveHint=false), so the description focuses on describing the rich return payload, which is valuable behavioral context. It also notes the error case { error } for unknown ids. However, since no output schema exists, the description of the return shape could be more structured, but it is thorough enough.

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, front-loaded with the core purpose, followed by a detailed list of returned fields. The list is comprehensive but could be seen as slightly verbose, though each field earns its place given no output 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?

Given no output schema, the description effectively enumerates the return values, which is important. It also covers error behavior. However, it could mention any pagination or rate limits, but for a simple get-by-id tool this is largely 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 100%, so the schema already documents the 'id' parameter fully. The description adds minor clarification about accepting legacy project-key values, which is slightly beyond the schema, but mostly repeats.

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 project) and clearly distinguishes from sibling search_projects by emphasizing 'Full detail for one project' by id. The id semantics (Omeka o:id) are also clarified.

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

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

Implies usage for retrieving a single project's detail, but provides no explicit guidance on when to use this vs search_projects or fetch. No exclusions or prerequisites are 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, non-destructive), so the description earns credit for going further: it discloses that full text is omitted by default, that long texts are paged, that BibTeX is the default citation format, and that an unknown id returns { error } rather than throwing. That is genuinely useful operational context beyond the annotations.

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

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

Front-loaded with the resource and its contents, then moving to the high-value behavioral notes (fulltext gating, citation, error case). The opening catalog of linked fields is listy but each clause corresponds to real returned data, so it largely earns its space.

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

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

With no output schema, the description carries the full burden of describing return values and does so thoroughly, including paging behavior for long full texts and the unknown-id error shape. It is nearly complete; only the absence of alternative-tool routing keeps it from the top.

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, citation_format, and the three fulltext parameters, making 3 the baseline. The description confirms defaults (BibTeX, full text off) and adds the paging/error context, but adds little syntax or format detail the schema does not already carry.

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

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

The description clearly identifies the resource (a publication) and enumerates what the call returns: metadata, linked entities, conference details, access statements, advisers, links, and a citation export. This is specific enough to distinguish it from search_publications or list_publication_facets, though it never explicitly names those siblings as 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?

There is no explicit guidance on when to use get_publication versus search_publications or how to obtain a valid id. The only usage-adjacent content is the note that full text requires include_fulltext=true, which is a parameter behavior rather than a routing rule.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral detail beyond that: long text fields are truncated at 25,000 characters, an unknown id returns { error }, and the citation string is generated from the returned fields because items rarely carry their own citation.

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 purpose and efficient overall; the long but informative field enumeration and the two trailing sentences (citation generation, truncation/error) all carry useful content. Slightly dense as a single run-on field list 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 no output schema, the description carries the full burden of describing returns, and it does so thoroughly: the metadata field list, the generated citation/bibtex/ris/csl-json outputs, the truncation limit, and the error shape. An agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the id format and the citation_format enum mapping. The description restates that citation_format swaps BibTeX for RIS or CSL-JSON, adding framing but little beyond the schema, 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?

States a specific verb (get) and resource (one research item) and then enumerates the exact payload an agent receives: dates, contributors, subjects, places, collections, citation fields, etc. This clearly distinguishes it from sibling list/search tools like search_research_items and get_collection_overview.

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 name and the 'full metadata for one research item' framing plus the id-based signature, so an agent can infer this is the detail-fetch counterpart to search. However, there is no explicit guidance on when to prefer this over the sibling get_* tools or a signal to call search_research_items first to obtain an id.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: case-insensitive name matching, the exact funding_phase values returned, and a structured { error } with available_values on unknown names.

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

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

The core action and resource lead the sentence, and the long return-value enumeration earns its space because there is no output schema. It is dense but not padded, though the trailing list of returned fields is close to overload.

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 takes on the return-value burden and does so well, enumerating the returned fields including the citable amira_url and item counts, and documenting the error case. Only the routing to alternative tools remains unaddressed.

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

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

Schema coverage is 100% and the schema already gives an example value, so the baseline is 3. The description adds semantics the schema lacks: matching is case-insensitive and accepts alternate casing such as 'Mobilities'.

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 ('Full detail for one research section by `name`') and scopes it to a single section, which cleanly separates it from the sibling list_research_sections. The example name makes the expected input concrete.

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 'Full detail for one research section', which contrasts with listing tools, but no alternative is named explicitly and there is no statement of when to prefer this over search or list_research_sections. The unknown-name error path gives a discovery hint ('available_values') but this is reactive rather than proactive guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real behavior beyond them — transcripts are suppressed by default to avoid large payloads, only has_transcript + transcript_length are shown, and an unknown id yields { error }. Not fully rich (no pagination limits discussion beyond transcript_max_chars, no rate/auth notes).

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

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

Front-loaded with the resource and its returned fields, then the transcript caveat, then the error case. Dense but every clause earns its place; no filler.

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

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

With no output schema, the description carries the return-shape burden and does so: it names the fields returned, explains the transcript omission and its workaround, and documents the error response. Nothing essential for a correct call 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 the schema already documents the four parameters. The description adds nuance the schema lacks: the default-off rationale, the coupling of include_transcript with transcript_offset for paging, and the error return 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) plus resource (one YouTube video) and enumerates the returned fields (upload date, abstract, playlists, speakers, languages, watch URL, citable amira_url). An agent can distinguish this from siblings like get_research_item or search_videos without opening the 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?

Gives clear operational context: transcript is omitted by default and the caller should pass include_transcript=true and page long transcripts. It does not, however, name an alternative tool or say when not to use it (e.g. when search_videos suffices), so it stops short of explicit when/when-not routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior beyond that: results are ranked by item count and language values carry an ISO code, which tells the agent what ordering and shape to expect.

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 what the tool returns and followed by the actionable mapping. Every clause earns its place; no boilerplate or repetition of 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 carries the return-value burden and does so partially: it explains the distinct values, their count-based ranking, and the extra ISO code for languages. It omits details like the count field name or pagination behavior, but an agent can call it correctly.

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

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

Schema coverage is 75% and already documents the category enum, the genres/formats alias, and the tags-merged-into-subjects note. The description adds the mapping from facet values to the specific search_research_items filter names, which is meaningfully beyond the schema's enum listing.

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 the distinct values of one categorical facet across research items') and adds scope detail (ranked by item count, ISO codes for languages). It does not explicitly contrast with near siblings such as list_publication_facets or list_years, so it stops short of full sibling differentiation.

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

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

Clearly explains the downstream purpose: values are meant to be fed back into matching search_research_items filters, and it maps which filter each facet feeds ('genre' for formats, language, resource_type). It gives no explicit when-not-to-use or alternative-selection guidance, so it is strong context rather than full routing.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. Beyond that the description adds useful content-level context: results carry coordinates, Wikidata URIs, authority ids, and citable amira_url links, which matters since no output schema exists.

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

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

Three tight sentences, front-loading the resource and scope before the optional parameter and return-shape details. Domain vocabulary is dense but every sentence carries information.

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

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

With no output schema, the description usefully enumerates what results contain, and the read-only annotations carry the safety profile. An agent has enough to call it correctly; only the absence of routing guidance to sibling list tools is a gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the accepted values and clarifies the parameter is keyed to the Omeka partner-category authority and also accepts a free category label, but adds no syntax or default beyond the schema.

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

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

States a specific verb (List) and resource (Africa Multiple partner institutions) and enumerates the four partner categories it covers. The scope is narrow and unambiguous, though it does not explicitly distinguish itself from the sibling list_institutions.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative tool (e.g. list_institutions for the broader institution set) is named. Usage is only weakly implied by the mention of categories.

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 real behavioral context beyond them: results are ranked by item count and each entry carries a browsable page. Pagination behavior for limit/offset is not mentioned.

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

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

Front-loads the verb and resource, uses an em-dash aside for the taxonomy, and closes with the actionable routing sentence. The middle enumeration of collection types is slightly padded but each item is genuinely informative.

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 describe returns (item-count ranking, browsable page per collection), which is the key missing piece an agent would otherwise lack. Only the offset parameter and pagination semantics are left unexplained.

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

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

Schema coverage is 67% (limit and keyword documented, offset undocumented). The description adds nothing about any of the three parameters, so it neither compensates for the offset gap nor clarifies ranking interaction with limit. Baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific verb (list) and resource (collections), then defines the domain term precisely as Omeka item sets with the three subtypes it covers (project collections, external archives, curated sets). It is clear an agent is enumerating collections, but it never explicitly distinguishes itself from sibling get_collection_overview, which an agent would need in order to pick correctly between the two.

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 downstream guidance: feed a title or id into the `collection` filter of search_research_items, which tells the agent this is a discovery/lookup step in a larger workflow. No exclusions or explicit 'do not use when' conditions, and listing vs. single-collection detail is left implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: each result contains contributed_item_count and a citable amira_url, and it discloses that the underlying data is an authority record of type 'Group'. It doesn't explain rate limits or caching, but that's minor for a read-only list 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 sentences, front-loaded with the core purpose, then filtering/pagination, then return fields, then cross-tool guidance. No filler or redundant repetition despite covering several distinct pieces of 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 0-required-parameter, read-only list tool with an output schema absent, the description covers resource definition, filtering, pagination, return fields, and a cross-reference to a sibling. The only gap is that 'offset' semantics are not explained, but that is a standard pagination parameter.

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

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

Schema description coverage is 33%: only 'limit' has a description in the schema (and it's the same as the description's text). The description adds meaning for 'keyword' ('filters by name') which the schema does not document, and reiterates the default/max for limit. Offset is still unexplained, but the key ambiguity (what keyword filters on) is resolved.

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 (List) and resource (research groups), and clarifies the resource's underlying type ('organisation authority records typed Group'), which distinguishes it from siblings like list_institutions and list_collections. An agent can tell this apart from other list tools immediately.

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 to the alternative: 'Use get_institution with the group's name for its items.' It also implies that keyword-filtered enumeration is the use case here. This is a clear when-to-use-this vs. when-to-use-sibling statement.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered. The description adds substantive behavior beyond them: the fields each result carries (name, project_count, coordinates when reconciled, citable amira_url) and pagination limits, though it does not state total-count or ordering behavior.

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

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

Three tight sentences, front-loaded with purpose, then parameters, then result shape, then sibling routing. No sentence is redundant and nothing is buried.

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 enumerating the returned fields. With annotations covering safety and both alternatives named, an agent has everything needed to call this correctly.

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

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

Schema coverage is only 33%, so compensation is needed. The description supplies the missing semantics: keyword filters by name (schema says only 'string'), and offset is described as paginating alongside limit. Limit's default/max merely restates the schema 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 ('List institutions in the authority list'), and explicitly distinguishes itself from two siblings: get_institution (details) and list_groups (research groups are a separate list). An agent can select 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?

Routes explicitly: 'Use get_institution for the affiliated projects and contributed items' and 'Research groups are a separate list — see list_groups.' Both the when-to-use alternative and the boundary with a similar list are named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuine behavioral context the annotations do not: the result ordering (by publication count) and the returned attributes (ISSN, country, website). It does not mention pagination or result-size behavior, which keeps it at a 4 rather than 5.

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

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

Two sentences, both earning their place: the first defines scope and output, the second gives the integration path. No filler or redundant restatement of 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 no output schema, the description compensates by naming the returned fields and their ordering, which is exactly what an agent needs to consume results. The main gap is paging behavior (limit default 50 / max 200, offset) and whether the ranking is scoped to the cluster only, which would round this out to a 5.

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

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

Schema description coverage is 67% — limit and keyword are documented in the schema, offset is not. The description adds no parameter-level detail (no example of the `keyword` substring semantics, no mention of paging). Baseline 3 is appropriate when the schema carries most of the load.

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 the journals the cluster publishes in'), identifies the underlying entity (Journal venue authority), and specifies the ordering (ranked by publication count) plus the fields exposed (ISSN, country, website). It is immediately distinguishable from sibling list_* tools such as list_institutions, list_subjects and list_years.

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 a downstream action: feeding a journal title into the `venue` filter of search_publications. That is clear, actionable context. It stops short of a 5 because there is no when-not guidance (e.g., when to prefer list_publication_facets or search_publications directly for venue discovery).

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, so safety is covered externally. The description adds genuinely non-obvious result semantics: countries and cities share ONE flat list with no selectable level, and the hierarchy is rolled up so Lagos counts toward both Lagos and Nigeria. That rollup/counting behavior is real value beyond the annotations; only pagination/return-shape detail is absent.

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 densely packed sentences; the flat-list/rollup rule is front-loaded before the filter hand-off. Every clause carries information, though the parenthetical aside makes the first sentence slightly harder to parse than necessary.

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

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

No output schema exists, so the description must explain return content — and it does (ranked by count, coordinates where known, flat multi-level list). What is missing is pagination/limit behavior for the 4-param surface, but the core shape an agent needs to call and interpret it correctly is present.

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

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

Schema coverage is 75% (limit, country, keyword documented; offset bare). The description adds no parameter-level detail — no syntax hints for `keyword` or `country` matching — so it does not compensate for the undocumented offset. Baseline 3 is appropriate when the schema carries most of the meaning.

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

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

States a specific verb+resource ('List every place the research items come from'), plus two distinguishing behaviors: ranked by item count and coordinates where known. An agent can tell it apart from sibling list_* tools (list_institutions, list_subjects) 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?

Gives an explicit downstream usage path: 'Feed a name straight into the `location` filter of search_research_items.' That is clear, actionable context. It stops short of stating when *not* to use it (e.g. versus list_institutions for organization-based geography), so it misses the top band.

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 genuinely non-obvious semantics: one count per value per publication, missing_values for records lacking the facet, and count-descending ordering with pagination. It stops short of stating how filters combine (AND/OR) or how missing_values is 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?

Three dense sentences with no filler, front-loaded with the counting behavior, then accuracy caveats (one count per value, missing_values), then ordering/pagination and the downstream use. Nothing is redundant with 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 a rich annotation set and a declared output schema, the description does not need to explain return shape, and the counting/pagination semantics plus downstream filter usage cover the essentials. Remaining gaps: no sibling disambiguation against list_years/list_subjects and no clarification of how the 12 filter params compose.

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 most parameters are self-documented; the description adds the key insight that the filter parameters scope the counted bibliography. It does not explain semantics for year_from/year_to, keyword scope beyond the schema text, or how `facet` interacts with the returned values. Baseline 3 is appropriate.

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

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

Names a specific verb (count) and resource (publications) and enumerates the facet dimensions precisely, which tells an agent exactly what comes back. It does not, however, distinguish itself from sibling list_* tools (list_years, list_subjects, list_categories, list_journals) that plausibly return overlapping value sets.

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 values in search_publications filters' gives the downstream purpose, and the schema's `type` param echoes the round trip. But there is no when-not guidance, no statement of how this differs from list_subjects/list_years, and no indication of whether the filter parameters must mirror the ones passed to search_publications.

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/closed-world, so the bar is lower; the description adds real value by disclosing the return shape (phase, PIs, counts, citable amira_url) and a data caveat that AM 2.0 sections are newly seeded and currently hold ~0 projects/items, which prevents the agent misreading empty results as an error.

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 purpose and invocation constraint, then adds detail. The enumeration of all twelve section names is lengthy but does help the agent recognize the expected output; it is the one passage that could be trimmed without losing invocation-relevant meaning.

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

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

There is no output schema, so the description carries the burden of describing return values, and it does so concretely (funding phase, PIs, member/project/item counts, amira_url). Combined with the seeding caveat and the sibling pointer, an agent has everything needed to call and interpret this 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?

Zero parameters, so the baseline is 4. The description confirms 'Takes no arguments,' which matches the empty schema and additionalProperties:false, leaving no ambiguity about how to invoke it.

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 ('List') and resource ('the cluster's research sections'), and immediately qualifies the scope as 'top-level thematic structure' with the return fields (funding phase, PIs, counts, amira_url). It is clearly distinguishable from get_research_section, which returns a single section's detail.

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: use get_research_section 'for one section's full description and project list.' This gives a clear alternative and the condition that selects it, though it doesn't spell out a when-not for this tool beyond that single contrast.

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, and non-destructive behavior, so the bar is lower. The description adds real domain context beyond them: results are count-ranked, each subject links to an authority page, and subjects absorbed the former tag facet. It omits pagination/limit behavior, which 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?

Three tight sentences, front-loaded with what it lists and how results are ranked. The tag-facet sentence earns its place as disambiguation; the closing authority-page clause is slightly dense but not wasteful.

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 the return: ranked subject headings with per-item counts implicit in the ranking and an authority page per subject. Pagination via offset is unaddressed, a minor gap for a 3-parameter read-only listing 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?

Three parameters at 67% schema coverage: `limit` (default 50, max 300) and `keyword` (substring filter on the heading) are documented in the schema, while `offset` has no description anywhere. The description adds no parameter syntax or filtering detail, so it performs at the baseline rather than compensating for the offset gap.

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

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

States a specific verb and resource (list subject headings) plus the ordering rule (ranked by item count) and the return shape (each subject's own authority page). It is clearly distinguishable from siblings like list_categories, list_years, and list_journals, which cover different facets.

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 downstream: feed a value into the `subject` filter of search_research_items to retrieve items, and clarifies that free-form tags no longer exist as a separate facet. It does not state when to prefer this over browsing the similarly-named list_categories/list_years, so it stops short of full when/when-not guidance.

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

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

Goes well beyond the readOnly/idempotent annotations: it explains that range-dated items count toward every spanned year so bucket sums can exceed dated_items, discloses the accompanying dated_items/undated_items/year_range fields, and notes the absence of amira_url because years lack authority pages. This is exactly the behavioral context annotations cannot carry.

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 tightly packed sentences with no filler; the core purpose is front-loaded before the counting semantics and the amira_url caveat. Every sentence carries non-redundant information.

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

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

With no output schema, the description compensates by naming the returned fields (dated_items, undated_items, year_range) and the missing amira_url, and by spelling out the counting semantics. Nothing an agent needs to interpret or call the tool is absent.

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 from/to/bucket/sort/limit are already documented in the schema. The description reinforces the year-vs-decade bucket semantics but adds no syntax, default, or range detail beyond the schema, making the baseline 3 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?

States a specific verb+resource ('Date histogram of the research items') and scope ('how many fall in each year (or decade) of their content dates'), immediately distinguishing it from sibling item-listing tools like search_research_items. An agent can tell what it produces without opening the 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?

Names concrete use cases ('coverage-over-time and most-covered-year questions') and links the output back to the year_from/year_to filter of search_research_items, giving clear context for when to reach for this tool. It stops short of explicit when-not or alternative-tool routing, so it lands just below the top band.

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 bar is lower. The description adds genuinely useful behavior: accent-insensitive matching, full-text depth into publications and transcripts, the exact return shape, and the id-to-fetch handoff.

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

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

Front-loads the core purpose and scoping, then the return contract and the sibling pointer. Dense but each sentence carries information; the parenthetical about the OpenAI entry point is slightly tangential but useful for routing.

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 detail returns, yet it still names the result fields and the follow-up fetch step. Scope, matching behavior, and alternatives are all covered, so nothing an agent needs 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 all three parameters are already documented, including the 'concise queries beat full sentences' guidance. The description adds no further parameter syntax or semantics beyond what the schema provides, 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?

States a specific verb and resource ('Search the Africa Multiple (AMIRA) research collection') and enumerates the covered corpora (items, bibliography, podcasts/videos, projects/sections). It clearly distinguishes itself from the richer sibling search_* tools by 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?

Names alternatives (search_research_items, find_related, list_*) and frames itself as the OpenAI/ChatGPT-compatible entry point, which implies when to pick it. It does not state an explicit when-not condition or routing rule beyond 'richer filtered tools are also available'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavioral detail: names are stored 'Surname, Forename' but matching is order-independent and accent-insensitive. It does not mention pagination or result ordering behavior, which keeps this from a 5.

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

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

Two sentences and a closing pointer, front-loaded with the resource and the matching rule. The worked name examples earn their space by clarifying order-independence without extra prose.

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 search with no output schema and strong annotation coverage, the description supplies what an agent needs: what is searched, how matching behaves, and where to go for full profiles. It omits pagination/result-shape guidance, which is a minor gap given limit/offset appear in the schema.

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

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

Schema coverage is 75%, so most parameters are already documented in the schema. The description adds real meaning for the matching semantics of the keyword parameter via the worked examples ('Oliver Baumann', 'Baumann, Oliver', 'Baumann'), but says nothing about limit/offset/affiliation, so it sits at the baseline for a well-covered 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 the people authority list') and scopes it ('researchers and contributors'), which cleanly separates it from siblings like search_publications or search_projects. It also names get_person explicitly, so the agent can distinguish the lookup path from the detail path without opening schemas.

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 closing sentence 'Use get_person for a full profile' gives a clear alternative and the condition that selects it (want the full profile rather than a match). It stops short of stating when-not to use this tool (e.g. when you already have an exact ID), but the routing guidance is concrete.

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, yet the description adds genuine behavioral detail: corpus size, AI-generated transcripts, and that transcript-only hits are flagged via matched_in:'transcript' with a transcript_snippet. That return-shape disclosure is useful in the absence of an output schema; it only lacks pagination/ordering semantics.

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 the verb+resource and scope before the alternative-tool routing. Dense but each clause carries information; the parenthetical example of the series title is slightly decorative but harmless.

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

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

With no output schema, the description compensates by explaining the matched_in/transcript_snippet hit annotation and how hits are surfaced; all seven parameters are optional and mostly self-documented. What is left unspecified (ordering, pagination behavior beyond limit/offset) is minor for a search tool.

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

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

Schema coverage is 86%, so the baseline is 3, and the description adds the cross-parameter semantics the schema cannot express: filters are optional and AND-combined, and the keyword parameter reaches into the transcript rather than just title/abstract. That last point is a meaningful clarification of keyword behavior.

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

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

States a specific verb and resource ('Search the cluster's podcast episodes') and goes further by explaining the scope of the search (reaching into AI-generated transcripts) and the size of the corpus (~43 episodes). It also names the sibling get_podcast and its distinct purpose, so the agent can separate the two 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 routes single-episode use to get_podcast ('Use get_podcast for one episode's detail and the transcript itself'), which is a clear alternative-and-condition pairing. It also notes filters are optional and AND-combined. It stops short of distinguishing itself from the generic `search` sibling, leaving one inference gap.

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/openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: the AND-combination rule for filters and the meaning of `item_count` (only a subset carry digitised items). It doesn't cover pagination or response format, but those gaps are minor given annotation coverage.

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

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

Three tight sentences, front-loaded with scope, then the filter-combination rule, then the routing hint. Every sentence carries information and none restates the name or 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?

For an 8-param tool with no required fields and no output schema, the description covers tool purpose, filter behavior, and output-field semantics well. Return shape is only partially covered (item_count highlighted, but not the full record), leaving a small 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 88%, so per-parameter meaning is largely handled by the schema. The description still adds cross-parameter semantics the schema cannot express: filters are AND-combined and omission means no filtering, which affects how the 8 optional params should be combined.

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 (research projects), then scopes it precisely to partner/source metadata labels plus external collections. It distinguishes itself from the sibling search_* tools by naming get_project as the detail alternative.

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

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

Explicitly states that filters are optional and AND-combined and that omitting all of them lists every project, which tells the agent exactly how to use the tool for both filtered and browse use cases. It names get_project as the alternative for full detail, though it doesn't contrast against the generic `search` sibling.

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, but the description adds real behavioral context: filters are AND-combined, results are newest-first, keyword penetrates extracted PDF text (surfacing matched_in='fulltext' plus a snippet for text-only hits), exports omit abstracts/full text, and amira_url should be the citation link. This goes well beyond the annotation surface.

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?

Information-dense with no filler sentences, and the core purpose plus scope is front-loaded. It is slightly packed with parallel clauses (export, pagination, citation) that could be separated, but every sentence earns its place.

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

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

For a 12-parameter, no-required-argument search tool with no output schema, the description supplies the missing return semantics: matched_in, snippet, has_more, next_offset, and citation link guidance. Nothing an agent needs to call or iterate it correctly is absent.

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 most parameters are self-documented, yet the description still adds meaning: keyword's reach into full text, citation_format's effect on output completeness, and the AND semantics across filters. It stops short of clarifying ambiguous params like year_from/year_to bounds or has_fulltext interaction.

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 ERef/EPub cluster bibliography') and immediately distinguishes itself from siblings by naming list_publication_facets for discovery and get_publication for detail. An agent can tell what this tool does 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 to alternatives with conditions: use list_publication_facets for facet values, get_publication for detail, and set citation_format when exporting. Also gives the iteration protocol (follow next_offset until has_more=false), so when and how to use it are both covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context beyond them: AND-combination of filters, browse-when-empty semantics, and — with no output schema — the no-match `suggestions` field that names which filter to drop and how many items that would surface.

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 'The main discovery tool' and the corpus size, then routing to the sibling, then the edge-case response behavior. No filler or restated name/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?

For a 16-param, zero-required search tool with no output schema and annotations covering safety, the description covers purpose, filter interaction, fallback behavior, and the detail-lookup alternative. Only minor gaps remain, such as pagination/result-shape expectations, and limit/offset defaults are already documented in the schema.

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

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

Schema coverage is 94%, so parameters are largely self-documenting and the baseline would be 3. The description adds cross-parameter semantics the schema cannot show: that all filters combine with AND and that omitting every filter is a valid browse mode, which meaningfully changes how the 16 params should be used together.

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 ~4,000 research items ... digitised artefacts — images, texts, audio, video') and scopes it to all Africa Multiple project collections. It also distinguishes itself from the sibling get_research_item, which returns one item's full detail.

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 usage patterns ('items about subject X', 'items from location Y'), states that filters are optional and AND-combined and that omitting them browses everything, and names the alternative get_research_item. It does not, however, contrast itself with the generic `search` sibling, so routing among the search* family is still partly inferred.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond that: keyword search reaches INTO transcripts and flags hits as `matched_in: 'transcript'` with a `transcript_snippet`, plus the AND-combination of filters.

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?

Compact and front-loaded: scope first, then keyword/transcript behavior, then the get_video pointer. Every sentence carries information, though the parenthetical is slightly dense.

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 responsibly describes the notable return fields (matched_in, transcript_snippet). For an 8-param, 0-required search tool with rich schema coverage, this is nearly complete; only pagination/result-shape breadth is left implicit.

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

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

Schema coverage is high (88%), so the baseline is 3. The description adds semantics on top: it explains that keyword spans title, abstract and transcript, and that filters combine with AND, which goes beyond the raw parameter list.

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

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

States a specific verb (search) plus resource (Africa Multiple YouTube channel videos), and scopes it precisely (~140 lectures, interviews, events; most with transcripts). It also distinguishes itself from the sibling get_video by assigning detail retrieval there.

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 names the alternative for detail work ('Use get_video for one video's detail and the transcript itself') and notes that filters are optional and AND-combined. It doesn't address when to prefer this over the general 'search' or other search_* siblings, so it stops short of full routing guidance.

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