AMIRA — Africa Multiple Research Data

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds real behavioral value beyond that: it discloses the cardinality bound (2–4), the fact that one filter set is applied uniformly across all cohorts, the output dimensions reported, and that overlapping collections are allowed rather than deduplicated.

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 compact sentences, front-loaded with the action and cardinality, followed by output expectations and a single caveat. 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?

An output schema exists, so return values need not be explained, and the description's summary of reported metrics is a helpful supplement rather than a requirement. Combined with annotation coverage of the read-only profile, an agent has enough to call this correctly; only per-filter semantics remain thin due to the 0% schema coverage.

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

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

Schema description coverage is 0%, so the description carries the full burden. It usefully clarifies that `filters` is shared/identical across all `cohorts` and that `cohorts` accepts projects or item sets sized 2–4, but the roughly twenty filter fields (genre, country, year_from/to, has_media, etc.) receive no explanation, so compensation for the coverage gap is only partial.

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 ('Compare 2–4 projects or item sets') and immediately scopes the operation to a comparison across cohorts. This clearly distinguishes it from the sibling list_/get_/search_ tools, which retrieve a single entity or a flat result set. It also previews the output dimensions (denominators, missingness, dates, top types/languages).

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

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

'Compare 2–4 projects or item sets with identical research-item filters' gives a clear condition for use: multi-cohort comparison under one filter set. The caveat 'collections can overlap' warns about a likely misuse assumption (that cohorts are disjoint). However, no sibling alternative is named for the single-collection case (e.g., get_collection_overview or list_collections), so routing guidance is 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 cover readOnly/idempotent/non-destructive, so the description's job is to add context — and it does: fulltext/transcript are opt-in and pageable, content respects an exposure policy, and an unknown ID errors rather than returning empty. That is meaningful behavior beyond the structured hints, though it omits whether errors are distinguishable by type.

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

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

Two sentences, no filler, with the core read purpose front-loaded ahead of the opt-in paging and error details. Every clause carries information.

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

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

With an output schema present the description need not explain return values, and the read-only annotations cover safety, so what remains is largely sufficient. The missing piece is routing relative to the typed getter siblings and any auth/exposure prerequisites.

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 8 parameters including the include_/offset/max_chars family. The description's 'opt-in and pageable' phrasing echoes this but adds no syntax, interaction rules (e.g., offset requires the matching include flag), or default guidance 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 (read) and resource (a typed search result / AMIRA record) and adds the 'as a cited document' framing. However, it never distinguishes itself from the typed siblings (get_publication, get_podcast, get_video, get_research_item), so an agent cannot tell from the description why it would call fetch with 'pub:30001' instead of get_publication.

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 through 'read a typed search result' and 'full text/transcripts are opt-in', which tells the agent this follows a search. But there is no explicit when-to-use/when-not, no mention of the typed getter alternatives, and no prerequisites or exposure-policy preconditions spelled out.

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, non-destructive behavior, so the safety profile is covered. The description goes beyond that by disclosing dedup semantics (per-corpus counts deduplicate each record), a seed-specific quirk (subject/person seeds also include publications), and return characteristics (ambiguity, cited samples). These are real behavioral details not present in structured fields.

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

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

Three compact sentences with no filler, and the resource scope is front-loaded before the count/return mechanics. Slightly terse and jargon-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 does sketch return content (ambiguity, cited samples, per-corpus counts), which helps. However it omits any usage framing and doesn't explain how 'connected through shared records' is determined, leaving the agent to guess when this tool beats its graph/entity siblings.

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% and the schema already documents the pivot semantics for each entity_type in detail. The description only echoes the entity categories covered by the enum, adding no format or value syntax beyond the schema. Baseline 3 is appropriate.

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

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

The description names a resource — subjects, people, places and projects connected through shared records — so the agent can infer a relationship-discovery tool. But it is a noun fragment with no explicit verb ('find', 'pivot') and never distinguishes itself from siblings like get_entity_graph or resolve_entity, which also concern entity connections. Purpose is implied 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?

There is no when-to-use guidance, no statement of preconditions, and no mention of any alternative tool. The agent gets no help deciding between find_related, get_entity_graph, or resolve_entity for a given entity question.

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, destructiveHint=false and closed-world, so the safety profile is fully covered. The description adds the fact that it reports snapshot freshness and refresh status, which is mildly useful context, but does not mention auth, rate limits, or cost beyond that.

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 ('Start here: ...') with no filler; each listed item earns its place by signalling returned content. It is a fragment rather than a full sentence, but it is efficient.

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

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

For a zero-parameter, read-only tool with an output schema that already documents the return shape, the description is nearly complete. It could do more to differentiate from sibling aggregate tools, but nothing essential 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate at the parameter 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 names concrete outputs (corpus counts, text coverage, breakdowns, dates, snapshot freshness, refresh status), so an agent understands this is an aggregate overview of a collection. It does not, however, distinguish itself from siblings like get_data_quality or list_collections, which also report collection-level statistics.

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?

'Start here' implies the tool should be used first, giving implicit usage guidance. But no explicit when-to-use/when-not conditions are stated and no alternative (e.g. get_data_quality) is named for the cases where a different tool is appropriate.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the bar is lower. The description still adds real behavioral value: it scopes what is reported (coverage, unresolved authority links, sanitized refresh status) and warns that missing catalogue metadata is not evidence of real-world absence, which meaningfully shapes how an agent should treat the 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?

Two compact sentences, front-loaded with the reported facets and closed with the interpretive warning. Slightly dense and telegraphic, but no sentence is wasted 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?

For a zero-argument diagnostic tool with an output schema and full annotation coverage, the description supplies what is needed to invoke it correctly and to interpret the results. The only meaningful omission is any when-to-use framing relative to the many sibling lookup tools.

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 no parameters, so the baseline for this dimension is 4. The description introduces no parameter concepts that need elaboration and correctly stays at the level of what the call returns.

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 the resource (data coverage) and enumerates the specific facets reported: coverage gaps, missing metadata, unresolved loaded-authority links, and refresh status. 'Snapshot' is used loosely as a verb, but combined with the title 'Inspect data coverage' the agent understands this is the diagnostic view over catalogue quality. It is clearly distinct from the domain-lookup and search 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?

There is no statement of when to call this versus alternatives (e.g. get_snapshot_changes, list_collections) and no prerequisites. The closing sentence is a caveat about interpreting results, not guidance on selecting the tool, so the agent gets no routing help.

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/closed-world, so the safety profile is covered. The description adds genuine context beyond that: results mix explicit links with derived co-occurrence, each edge carries distinct-record counts and cited evidence, and pagination consistency requires pinning snapshot_id. That is meaningful behavioral disclosure for a read 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 dense clauses with zero filler, front-loaded with the core result shape followed by the two behavioural levers (filtering, paging). Every sentence carries information an agent needs; nothing restates the name or annotations.

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

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

With an output schema present, return values need not be described, and the description instead covers the graph construction, filtering semantics, and pagination invariants. For an 8-parameter tool the only real omission is any characterization of the offset parameter, which is undocumented in both description and 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 description coverage is only 38%, so the description must compensate, and it does: it explains types (pre-filter on neighbours, applied before bounds), edge_id (pages that edge's evidence), snapshot_id (pin for stable paging), and implies seed ('from a typed ID'). limit, max_edges and max_nodes are documented in-schema; only offset remains unexplained anywhere.

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: 'One-hop graph from a typed ID', and elaborates the two link classes (explicit catalogue links, derived co-occurrence) and what they carry (distinct-record counts, cited evidence). An agent knows exactly what it gets. It does not, however, name or contrast with the closest sibling, find_related, which also returns related entities.

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?

'types filters neighbours before the bounds' and 'Pass edge_id to page its evidence; pin snapshot_id across pages' give real operational guidance on filtering and paging. But there is no when-to-use vs alternatives statement, and no exclusion regarding find_related or list_cluster_partners, so usage is only implied for the discovery-vs-graph decision.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context such as pagination, authentication needs, or what happens when neither id nor name is supplied (0 required params).

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 compact sentence that front-loads the resource and lists the returned facets efficiently, though the phrase 'with citation links' is slightly ambiguous without further explanation.

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 profile lookup with only two well-documented optional params and no output schema, the description is adequate but leaves gaps regarding how the tool behaves when both or neither parameters are supplied, and it does not clarify output structure or how it relates to sibling lookup tools.

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

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

With schema description coverage at 100%, the baseline is 3. The description adds marginal value by surfacing the two retrieval modes (by identifier or by name/acronym) implied by the schema, but does not add format details 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?

The description states a specific resource (institution or group profile) and enumerates what it returns (identifiers, members, funded projects, credited items, citation links). It does not explicitly distinguish itself from the sibling get_person or list_institutions, but the resource is clearly an institution/group detail fetch.

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

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

No guidance on when to use this tool versus alternatives such as list_institutions, get_collection_overview, or resolve_entity. The agent must infer usage purely from the name and resource described.

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 a genuinely non-obvious behavioral trait beyond them: list sub-results are capped at 50 with totals reported, which tells the agent to expect truncated collections. It still omits whether a lookup miss errors or returns empty, but the cap disclosure is the kind of 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 short sentences, no filler, and the disambiguation advice is placed last where it is actionable. The opening noun list is dense but front-loads the returnable content, which is useful given there is 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?

With no output schema, the description usefully substitutes by naming the categories of data returned, and it discloses the 50-item cap. What remains missing is failure behavior for ambiguous or unmatched names and any guidance on which sibling tool to use instead — modest gaps for a simple two-param read.

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 params (id, name) are already fully documented including the homonym-disambiguation rule and accent/order tolerance for name. 'Use id to disambiguate' restates the schema's own wording, adding no new meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description enumerates what the tool returns (affiliations, identifiers, roles, credited items, publications, podcasts, videos, collaborators) but never states the action plainly — it reads as a field list rather than 'retrieve a person's profile'. An agent can infer the purpose from name/title plus the field enumeration, but nothing distinguishes it from search_persons or resolve_entity beyond the read/write shape.

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

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

The only usage guidance is 'Use id to disambiguate,' which is a parameter tip rather than when-to-use-this-vs-alternatives guidance. It never says when to prefer this over search_persons, resolve_entity, or get_entity_graph, nor what happens if only a name is supplied that matches multiple people.

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 useful behavior beyond that: the transcript is opt-in, bounded, and pageable, and the response discloses which model produced the transcript. It still says nothing about error/not-found handling or how paging terminates, so it is only moderately additive.

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?

It is compact — two sentences of roughly 25 words — with the return-value summary front-loaded before the transcript caveat. Minor deduction for the comma-splice, fragment-heavy style that makes it read as a field list rather than a crisp capability statement.

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 right thing by naming the returned fields (duration, audio file, citation link, transcript model) and by flagging transcript paging and bounding. It stops short of covering how to source the id, what happens when the podcast is missing, or default page size behavior, leaving small but real 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 description coverage is 100%, so all four parameters (id, include_transcript, transcript_offset, transcript_max_chars) are already self-documenting. The description's 'opt-in, bounded and pageable' phrasing loosely echoes those params but adds no new syntax, units, or constraints 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?

The description identifies the resource (podcast) and enumerates what the tool returns — detail, duration, audio file, citation link, transcript-generating model — so an agent can tell what it fetches. However, it uses a nominal fragment ('Podcast detail') rather than a verb, and never explicitly differentiates itself from close siblings like get_video or fetch.

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 versus search_podcasts, get_video, or fetch, and no mention that the required id is obtained from search_podcasts (that fact lives only in the schema). The only usage-flavored content is 'Transcript is opt-in,' which is really a parameter default rather than 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavioral context by disclosing the sampling behavior ('ten sample research items') and the presence of citation links, which the annotations cannot express. However, it omits any note on permission scope or truncation of the sample.

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 efficient sentence-fragment with no filler; every listed field earns its place. It is front-loaded with the resource and the most important content, though the absence of a leading verb slightly weakens the opening.

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 must carry return-value information, and it does so reasonably well by enumerating the payload components (team, sections, funders, item counts, subjects, sample items). For a read-only single-resource detail endpoint with a fully documented parameter and complete annotations, this is close to sufficient; a routing note versus siblings is the only 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 description coverage is 100%: the single 'id' parameter is fully documented in the schema, including the Omeka numeric form and the typed 'project:37700' form. The description adds nothing about the parameter, so the baseline 3 is correct.

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 is a noun-phrase inventory of payload contents ('Project description, team, sections, funders, item counts...') rather than a verb+resource statement. An agent can infer it fetches a project's details, but it never explicitly says 'retrieve a project' and offers no differentiation from siblings like get_collection_overview or search_projects.

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 guidance, no prerequisite mention, and no indication of how this differs from search_projects or search_research_items. The agent must infer usage entirely from the name and the field list.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description isn't burdened with safety disclosure. It still adds real context beyond them: BibTeX is the default citation format, full text is opt-in and paginated, and amira_url is the canonical citation source with DOI/repository links as secondary.

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, front-loaded sentences with no filler: it leads with what is returned, then the opt-in/pagination behavior, then citation guidance. Tight and well-ordered.

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 annotations carry the safety profile and no output schema exists, the description adequately covers the payload (metadata, citation formats, opt-in full text) for a single-record get. It leaves the mechanics of continuing pagination slightly implicit, so it is strong but not exhaustive.

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 id, citation_format, and the fulltext parameters (defaults, min/max). The description's mention of BibTeX default and paginated full text largely mirrors what the schema states, adding little beyond the 3 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?

States a specific verb (get) and resource (publication) and clarifies the payload is metadata plus citation export, so the agent knows it returns a single publication's data rather than a list. It does not name the sibling search_publications to distinguish list-vs-detail retrieval, so it falls short of a 5.

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

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

'Full text is opt-in and paginated' implies the retrieval context and how to expand results, but there is no explicit when-to-use guidance or exclusion versus search_publications / list_publication_facets. Usage is implied rather than stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds genuinely new behavioral facts, namely that long fields are truncated at 25,000 characters and that the payload aggregates linked entities, media, IIIF and a generated citation. It stops short of describing truncation signalling or what happens when an id is not found.

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 with no filler, and the payload enumeration is front-loaded. It loses a point only because the most decision-relevant information (the retrieval verb and its scope) is omitted rather than compressed.

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 compensates by listing what the caller receives, plus the truncation cap. It is adequately complete for a two-parameter read tool, though it never clarifies the id-form distinction that the schema itself carries.

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 both parameters (and the accepted id forms) are already documented in the schema. The description restates the three citation formats but adds no syntax or default behavior beyond the enum values already present, so 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 enumerates the response payload (metadata, linked entities, rights, media files, IIIF manifest, citation) but never states a verb or the resource being acted on; the ''get by id'' intent is only recoverable from the title and the schema. It also draws no boundary against siblings such as search_research_items, resolve_entity, or fetch, which an agent must choose between.

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 guidance and no mention of alternatives, despite several plausible competing tools in the sibling list (search_research_items, fetch, resolve_entity, get_entity_graph). The citation_format capability is surfaced but without saying when one would request it.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so safety is covered. The description adds the return shape (team, projects, per-project item counts), which is real value given there is no output schema, but it says nothing about behavior when both id and name are omitted or mismatched.

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 compact sentence with no waste, and the resource is front-loaded. It reads as a noun phrase rather than a sentence, which slightly weakens its force as a statement of action.

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 part of the job by sketching the returned fields, but it leaves the two-optional-parameter lookup model and failure modes unexplained for an agent deciding how to call 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 description coverage is 100%, with useful examples ('section:218', 'Arts & Aesthetics'), so the baseline is 3. The description contributes no additional parameter meaning such as which key takes precedence or what happens with zero params.

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 fragment names a single, specific resource (one research section) and enumerates its payload (description, team, projects, item counts), which separates it from list_research_sections and get_research_item. It lacks an explicit verb, but the resource and scope are unambiguous.

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

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

There is no guidance on when to use this versus list_research_sections or get_research_item, and no mention that id and name are optional lookup keys. The agent must infer that either identifier can be supplied.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the fallback behavior (returning snapshot IDs when fewer than two exist) and pagination intent, but says nothing about result size, ordering, or what happens when from_id/to_id are omitted.

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, each doing distinct work: core action, edge-case behavior, and alternative routing. Front-loaded with the primary purpose and free of 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?

An output schema exists, so return formatting is fairly excused, and the fallback behavior is disclosed. However, with 5 loosely documented parameters and no explanation of how snapshots are selected or defaulted, the definition is not complete enough for an agent to invoke it confidently.

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 20%, and the description adds no meaning for from_id, to_id, corpus, or offset. The core mechanic — whether omitting from_id compares the latest two snapshots or defaults to something else — is left entirely unstated, which is the single most important parameter question for this tool.

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

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

States a specific action and resource: paginating added/updated/deleted records between retained snapshots on this Omeka instance. The sibling list is large, and the description differentiates by naming the snapshot-comparison scope and pointing at search-tool alternatives, though it never says what 'retained snapshots' are.

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 routing rules: it lists snapshot IDs when fewer than two exist, and it directs agents to added_since on the search tools for recent additions without history. That is real when/when-not guidance, but nothing tells the agent how to choose between snapshots or which corpus defaults apply.

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), and the description adds genuinely new behavioral traits: accent-insensitive literal matching, no ranking, UTF-16 origin offsets, bounded context, and citations. This meaningfully exceeds what annotations disclose.

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, front-loaded fragments with no filler; the purpose leads and the constraints follow. It is appropriately sized, though the telegraphic phrasing slightly compresses several distinct claims into run-on clauses.

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 no explanation, and annotations carry the safety profile. The main residual gap is pagination/radius semantics, but the description supplies enough matching-context detail for a competent caller.

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 40% (offset, radius, and keyword have no schema descriptions), so the description must compensate. It hints at radius via 'bounded context' and at offset via 'UTF-16 offsets', but never clarifies that 'offset' is likely a pagination cursor distinct from the passage's text offset, leaving real ambiguity.

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 (Find) and resource (literal accent-insensitive keyword passages) with the scope of IDs it operates on, and the clause 'no semantic ranking' distinguishes it from the search-family siblings. It stops short of naming the alternative tool (e.g., search), so the 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?

'Requires full text exposure; no semantic ranking' gives clear context for when to reach for this tool over a semantic search, and implies the prerequisite for it to work at all. It doesn't explicitly name the sibling to use instead or an exclusion list, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the opt-in/bounded/pageable transcript behavior and that it discloses transcript provenance, but these largely restate what the schema parameter descriptions already say, limiting the marginal value.

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

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

Two sentences, front-loaded with the return contents, and no filler. The phrasing 'says how the transcript was produced when recorded' is slightly telegraphic, keeping it from a 5.

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

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

With no output schema, the description does carry the return-value burden and lists detail, thumbnail, citation link, and transcript provenance. Combined with annotations covering safety and a fully documented schema, it is nearly complete for a read tool, missing only explicit routing to siblings.

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 four parameters with defaults and bounds. The description's 'opt-in, bounded and pageable' mirrors include_transcript, transcript_max_chars, and transcript_offset without adding format or syntax detail, 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 names the resource and enumerates what it returns (video detail, thumbnail, citation link), so an agent can tell it apart from list/search siblings. It is a noun phrase rather than an explicit verb, and it never names search_videos as the counterpart, so it falls short of a 5.

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

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

There is no when-to-use/when-not guidance and no alternative is named. The only usage-flavored statement ('Transcript is opt-in') describes a parameter default rather than a condition for selecting this tool over search_videos or get_podcast.

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 safety is fully covered. The description adds the useful fact that results are 'Ranked' (frequency-ordered), but says nothing about pagination behavior, deduplication, or empty-result handling beyond what the schema implies.

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 short sentences with zero filler, and the resource identity is front-loaded. The first sentence is a noun phrase without a verb, which slightly reduces immediate parseability, but there is no waste.

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

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

With no output schema, the description must carry the return-value burden, and it only loosely characterizes the output as ranked facet values without describing shape, ordering, or pagination semantics. For a moderate-complexity facet tool this is adequate but leaves real gaps around the returned structure and how it relates to sibling facet tools.

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%, so the schema already documents limit, keyword and the category enum including the genres/tags aliasing. The description adds little parameter-level detail beyond listing the facet kinds, so it sits at the baseline rather than compensating for any gap.

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

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

The description names the resource ('formats, languages or resource types used by research items') and implies the verb (a ranked facet listing), so an agent can tell it produces category facet values. However, it omits a clear verb and does not differentiate itself from sibling facet listers like list_subjects or list_years; that routing hint only appears in 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?

'Feed values into the corresponding search filters' gives a clear downstream use case, implying this tool is a value-lookup for search filtering. It offers no explicit when-not guidance or sibling alternatives in the description itself (the list_subjects routing is buried in the schema enum), leaving usage implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description adds the useful detail that results are grouped by category and include citation links, but says nothing about pagination, result size, or what an empty cluster 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?

A single short sentence with the resource front-loaded and no filler. It is efficient, though it is arguably under-specified rather than optimally 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?

With no output schema, the description should convey return structure; 'grouped by catalogue category, with citation links' partially does this but leaves the grouping shape and citation format unspecified. Adequate but with a clear gap for a list tool.

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

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

Schema coverage is 100% and the single optional category parameter is documented in the schema with its accepted values (amrc | privileged | cooperation | global). The description adds no syntax or filtering semantics beyond that, so the schema does the heavy lifting and a baseline 3 is appropriate.

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

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

The description names a specific resource (cluster partner institutions) and a distinguishing trait (grouped by catalogue category, with citation links), so an agent can tell what it returns. It does not, however, differentiate itself from the many sibling list_* tools (list_institutions, list_groups, list_categories), leaving the 'cluster' concept undefined.

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 guidance and no alternatives named. With list_institutions and list_categories among the siblings, the agent has no signal for choosing this tool over them.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restatement. The description adds two useful behavioral facts beyond the annotations: results are ranked by research-item count and carry catalogue links, but says nothing about pagination behavior or result size limits.

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

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

Two short sentences, front-loaded with what the tool returns and followed by the downstream chaining hint. No filler, though the second sentence is a usage note rather than a structural necessity.

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 partly compensates by naming the ranking criterion and catalogue links, but it omits the shape of returned items (what fields, what the links look like) and leaves offset semantics undocumented. Adequate but with clear gaps for a list tool with three parameters.

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-schema, while offset is not described anywhere. The description itself adds no parameter meaning beyond what the schema provides, so the baseline 3 for high-but-incomplete coverage 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?

States a specific verb+resource ('Omeka item sets') and adds scope detail (ranked by research-item count, with catalogue links), which helps distinguish it from sibling listers like list_categories or list_subjects. It does not explicitly contrast with compare_collections or get_collection_overview, so it falls short of a 5.

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

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

The second sentence gives forward guidance ('Feed an ID into search_research_items.collection'), which tells the agent what this list feeds into, but it never says when to use this tool versus siblings such as compare_collections or get_collection_overview. Usage is only implied by the ranking/filtering framing.

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, destructiveHint=false, covering the safety profile. The description adds only that results include 'citation links,' which is minor context. It says nothing about pagination behavior or result ordering beyond what the schema implies.

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 named first. No wasted words, though it is arguably too sparse given the tool's role among many list_* siblings.

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

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

For a list tool in a dense family of list_* siblings, the description omits pagination behavior, result ordering, and any differentiation from list_institutions/list_journals. With no output schema, the agent gets little about what a 'group' record contains or how to page through results.

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

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

Schema coverage is 67% (limit and keyword documented, offset not). The description mentions browsing 'by name,' loosely tying to the keyword parameter, but adds no format or syntax detail beyond the schema. 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 clear verb+resource ('Browse research groups and associations') with a scope hint ('by name'). It is distinguishable from list_institutions, list_journals, etc. by the 'groups and associations' resource, though it doesn't explicitly contrast with those 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?

No when-to-use guidance. It doesn't say when to use list_groups versus search for a specific group by keyword, nor does it reference any alternative sibling. The 'keyword' param implies narrowing but the description gives no routing context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds return-content context ('project counts and citation links'), which is useful, but no pagination or rate-limit behavior is 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?

A single well-formed sentence with zero filler, front-loading the resource and how to match it. Efficient, though it could carry one more clause of guidance without bloating.

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, annotation-covered list tool with no output schema, the description states what is returned (project counts, citation links) and how to query it. Adequate; only pagination semantics and sibling routing are 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 67% – limit and keyword are documented in-schema, offset is not, and the description adds a concrete keyword example ('UJKZ') that the schema lacks. It picks up some of the slack but doesn't clarify offset, so baseline 3 fits.

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 clear verb (browse) and resource (institution authorities) with the search key (name or acronym, e.g. 'UJKZ'). An agent can distinguish it from get_institution by the plural/list framing, 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?

The word 'browse' and the keyword example imply discovery/listing use, but there is no explicit when-to-use statement, no exclusion of get_institution, and no guidance on when to prefer this over broader search tools.

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

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

Annotations already declare this a safe, idempotent, read-only, closed-world operation, so the safety profile needs no restatement. The description adds content-level context (results are ranked by linked bibliography records and include ISSN and catalogue links) that is not in the annotations, which is helpful given there is no output schema. It stops short of noting pagination, ordering stability, or empty-result 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?

A single front-loaded sentence with no filler; the ranking and available fields come first. It is appropriately sized for a simple list tool, though it is arguably too terse to route the agent among the many sibling list_* tools.

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, zero-required-parameter list tool, the description covers the resource and the notable return fields (ISSN, catalogue links), partly compensating for the absent output schema. It omits how results are ordered/paginated and any disambiguation from the numerous sibling list_* tools, leaving real 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%: limit states 'Default 50, max 200' and keyword describes the substring filter, while offset is only explained by its name. The description contributes nothing about parameters, so the baseline 3 for moderate-coverage schemas 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 defines the resource precisely as 'publication venues ranked by linked bibliography records,' which distinguishes a journal entity from generic collections, institutions, or subjects. The listing/retrieval verb is only implied in the text (the title supplies 'List'), so it is clear but not maximally 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?

There is no guidance on when to call this tool versus siblings like list_subjects, list_institutions, or search_publications, and no mention of prerequisites such as the keyword filter's role. The agent must infer usage entirely from the 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds a genuine non-obvious trait: ancestor rollups and non-mutually-exclusive counts ("One item can count under both city and country"), which warns the agent that counts can double. It still omits pagination/return-shape behavior, but that addition is real value 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?

Three short sentences, front-loaded with the entity type, no filler. It is efficient, though the middle sentence about city/country counts is telegraphic and would benefit from slightly more framing.

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 tool with nested objects and no output schema, the description should say more about the return shape (coordinates are mentioned, but not how counts or rollups are returned). Annotations cover the safety profile, so the gap is not severe, but the description is only minimally complete for a result-bearing discovery 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 86%, so the schema already documents bbox, near, country, keyword, limit and offset. The description adds only an implicit link between the emitted place names and search_research_items.location, contributing little parameter meaning beyond the schema; the baseline of 3 applies.

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

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

The description conveys that the tool surfaces places ("Research places with coordinates and ancestor rollups"), which tells the agent the resource is geographic entities, but there is no explicit verb and it never says plainly that it lists/discover locations. It is understandable but vague, and it does not distinguish itself from siblings like list_subjects or list_years beyond the geographic nature of the output.

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?

"Feed a name into search_research_items.location" gives a downstream handoff, which implies this tool is for discovering location names, but the description never states when to use this tool versus the other list_* or search_* siblings. Usage is implied rather than specified, and no exclusions 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 establish read-only, idempotent, non-destructive behavior, so safety is covered. The description adds genuinely new behavior: facets are computed over the entire filtered bibliography, not the current page, and results are ranked. That is exactly the trait that distinguishes facet aggregation from paginated search.

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 behavior and followed by the routing/parameter-equivalence note. No filler, no restatement of the tool 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?

An output schema exists, so return-value shape needn't be explained, and annotations cover the safety profile. However, for a 13-parameter aggregation tool the description is thin: it never clarifies the relationship to list_years/list_subjects, nor what a facet result contains (values plus counts), leaving a real risk of misrouting.

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 69% and the 13 parameters are largely self-documented (facet is an enum, limit/offset ranges are stated). The description contributes only the "same selection rules as search_publications" equivalence, which adds some meaning but no syntax or format detail beyond the schema. 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?

States a concrete verb+resource: returns ranked facets for the bibliography, scoped to the whole filtered set before pagination. That scope statement distinguishes it from paginated document retrieval like search_publications. It does not, however, distinguish it from siblings such as list_years or list_subjects, which plausibly return the same facet dimensions as flat lists.

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?

"Uses the same selection rules as search_publications" tells the agent the filter parameters behave identically, which is useful routing context. But it never says when to choose this tool over search_publications or over the overlapping list_years/list_subjects siblings, so the selection decision is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered structurally. The description's only added behavioral content is that the result includes the external-collection grouping, which is useful scope information. It says nothing about shape, size, or whether results are paginated or cached.

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 short sentences, roughly 17 words, with no filler or redundancy — genuinely tight. The only structural weakness is front-loading: the opening phrase 'Cluster research sections...' obscures the verb instead of leading with what the tool returns or does.

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 no-parameter, read-only list tool with no output schema, the description does convey the categories of content returned (sections, phases, counts, citation links, external collections). What is missing is the operation itself and any differentiator from the singular get_research_section, leaving the agent to infer the most decision-relevant fact.

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 there is nothing for the description to disambiguate; schema coverage is 100% and the empty object is self-explanatory. Baseline 4 applies for a parameterless tool.

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

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

The description names the resource (research sections) and enumerates what the grouping surfaces (funding phases, project/item counts, citation links), so the subject matter is identifiable. However, it never states the action clearly — 'Cluster' is an odd opener for a tool named list_* — and it does not distinguish itself from the singular sibling get_research_section. An agent can guess the domain but not the operation with confidence.

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 guidance at all. With ~35 siblings including get_research_section, list_collections, list_cluster_partners and list_subjects, the description should say when a caller wants aggregated sections rather than a single section or another collection listing. Nothing routes the agent.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context: the result is ranked by distinct research-item count, and headings are either controlled vocabulary or free tags. Pagination behavior 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?

Two tight sentences with zero filler, front-loading what the tool returns before the actionable usage hint. Every clause earns its place.

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

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

For a simple, annotation-covered list tool with no output schema, the description conveys both what is returned (ranked subject headings) and how to consume it. 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 coverage is 75%, so most parameters are documented structurally. The description's mention of LCSH vs. free tags loosely corresponds to the vocabulary enum but largely restates schema content, adding little syntax or format guidance beyond it. 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 states a specific resource (subject headings, LCSH or free tags) and a precise ordering rule (ranked by distinct research-item count), which an agent can distinguish from siblings like list_categories or list_years. The scope and content are unambiguous.

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

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

'Feed a heading into search_research_items.subject' gives explicit downstream usage, telling the agent why and when to call this tool in a workflow. It stops short of naming a when-not-to-use condition or a competing sibling, so it is clear context without 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds genuinely non-obvious behavior: a date range contributes to each spanned bucket, and undated items are counted separately. It goes beyond the structured fields, though it doesn't mention the limit cap or truncation 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 short sentences, front-loaded with the tool's purpose and output shape, with zero filler. Each sentence adds a distinct fact (what it returns, the bucketing rule, filter/pagination support).

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

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

An output schema exists, so return value details needn't be repeated, and the description covers filters, pagination, and the aggregation rule. It is nearly complete for a 7-param aggregation tool, missing only explicit routing guidance against sibling list/search tools.

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 (86%), so the baseline is 3, but the description adds meaning the schema cannot convey: that 'filters' are the shared research-item filter set applied before bucketing, and the bucket-spanning rule that governs how 'from'/'to' interact with 'bucket'. This is useful semantics beyond the per-field 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 names a specific output artifact — a research-item year/decade histogram with dated and undated counts — which is far more precise than the tool name 'list_years' alone. It does not explicitly contrast itself with sibling aggregation tools like list_publication_facets, 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative (e.g. search_research_items or list_publication_facets) for obtaining date distributions. 'Supports shared item filters and pagination' describes capability, not the condition under which this tool should be chosen over its siblings.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real behavior context by stating it returns ambiguity instead of silently merging names. It stops short of describing pagination semantics or empty-result behavior, but the disambiguation policy is the important disclosure.

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

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

Three short sentences, front-loaded with the core action, then the key behavioral guarantee, then the follow-up tool. No filler and nothing redundant with 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?

An output schema exists, so return-value explanation is not required, and annotations cover safety. The description supplies purpose, disambiguation policy, and next-step routing, which is nearly enough for a 4-param lookup tool; only the param semantics and alternative-tool routing are thin.

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% across four parameters, so the description must carry the burden. It only gestures at semantics via 'label or typed ID' (loosely mapping to query and type) and says nothing about limit or offset, leaving pagination behavior 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+resource ('Resolve a label or typed ID to cited candidates') and adds a distinguishing behavioral clause ('Returns ambiguity instead of merging names') that separates it from merge-style lookups. It does not explicitly contrast itself with the many search_* siblings, but an agent can still tell it resolves inputs to canonical IDs rather than searching for records.

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 downstream guidance ('Use a returned id with get_entity_graph or get_* tools'), which is genuinely useful chaining advice. However it never states when to pick this over search / search_persons / get_person, nor what to do when resolution returns multiple candidates or none — usage is implied 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 and closed-world behavior, so the safety profile is covered. The description adds real behavioral context beyond that: results are abbreviated (typed IDs, titles, citation URLs) and full evidence requires a follow-up fetch. No rate limits, pagination, or ranking caveats are mentioned.

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

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

Three short sentences, scope first, result shape second, next action third. No filler, no restatement of the tool name, and the most decision-relevant information is front-loaded.

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

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

For a low-parameter search tool with an output schema and full schema coverage, the definition is nearly sufficient: an agent knows what it searches, what comes back, and what to do next. The one missing piece is disambiguation from the many type-specific search siblings in a crowded namespace.

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%, and the schema itself carries strong parameter docs (query syntax guidance, limit default 10 / max 50, enumerated types). The description adds nothing parameter-specific beyond echoing the type list, so the baseline 3 for fully-documented schemas 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 (ranked search) and enumerates the resource kinds it spans (items, publications, videos, podcasts, projects, sections), which implicitly positions it as the cross-type search. It never explicitly contrasts itself with the six type-specific search_* siblings, 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?

'Fetch selected records for evidence' gives a follow-up workflow hint, but there is no when-to-use vs. when-to-use-an-alternative guidance. With six narrower search_* siblings available, the absence of routing advice (e.g. use this for mixed-type intent, use search_publications for publications only) leaves selection to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: name matching ignores accents and accepts either name order, and results are canonical/authority records with homonym ambiguity that resolve_entity handles.

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, zero filler, with the core purpose front-loaded and the disambiguation advice last. Every sentence carries information the 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 no output schema, the description still conveys what records are returned (canonical authority records) and how matching behaves. Pagination defaults are left to the schema parameter descriptions, which is acceptable for a four-parameter, order-free search.

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 schema already documents limit, keyword, and affiliation, but the description adds matching semantics not present there: input names tolerate accent variation and either word order. It does not clarify the keyword-versus-affiliation distinction, which is the only remaining ambiguity.

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 canonical person authority records'), which distinguishes it from the sibling get_person (single-record fetch) and the generic search tool. The 'canonical authority record' framing tells the agent what kind of objects come back, though it does not name the sibling it differs from explicitly.

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

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

It gives a concrete routing rule: 'Use resolve_entity to disambiguate homonyms,' naming an alternative tool and the condition that selects it. It stops short of saying when to use this search versus get_person for a known identifier.

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

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

Annotations already declare the safe read-only/idempotent/non-destructive profile. The description adds genuinely new behavior: text-only hits return snippets while full transcripts require a separate opt-in call to get_podcast. It omits pagination behavior despite limit/offset params.

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

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

Two tightly packed sentences with zero filler; the resource scope is front-loaded and the fallback-to-get_podcast caveat follows immediately.

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 characterizes the return shape (snippets vs full transcripts), which is the key thing an agent needs to know. Pagination and ranking semantics for the 8 optional filters are left implicit, a minor gap.

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

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

Schema description coverage is 88%, so the schema itself documents nearly all parameters (keyword matching rules, language ISO codes, partial series titles). The description adds no parameter-level detail, which is acceptable 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?

States a specific verb+resource ('Search podcast metadata and transcripts'), which cleanly separates it from siblings like search_videos and search_publications. It doesn't explicitly name a sibling it is not, but the resource scope is unambiguous.

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

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

Explicitly routes the agent to get_podcast for full transcripts and notes the opt-in requirement, giving a clear when-to-use-this-vs-that condition. No when-not guidance, but the alternative is named with its selection condition.

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 annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds return-format context (cited summaries and item counts), which is useful given there is no output schema, but it does not describe pagination behavior or 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?

Two sentences, both front-loaded and waste-free. The first states scope and the second states output plus the routing alternative.

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-required-parameter search tool with 88% schema coverage and rich annotations, the description covers purpose, scope, return shape, and the key alternative. The main missing piece is pagination or result-set behavior, but that is partially addressed by the schema's limit and offset fields.

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 88%, so the schema already documents nearly all parameters, including limit defaults, keyword matching, university facets, and PI name-order behavior. The description adds no meaningful parameter semantics beyond that, so baseline 3 is appropriate.

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

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

The description states a specific verb (search) and resource (projects), and names the exact fields searched: names, descriptions, and membership. It also explicitly distinguishes itself from the sibling get_project, so an agent can choose between them without opening either schema.

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

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

It gives a clear usage signal by directing the agent to get_project for detail, which implies search_projects is for discovery and summarized results. It does not spell out explicit exclusions or when-not-to-use conditions beyond that, but the alternative is 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 readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior: newest-first ordering, keyword matching against PDF full text with snippet returns, per-page citations under citation_format, and a single consolidated export file.

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

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

Four short sentences, front-loaded with the filter/sort semantics and then the three output-shaping modes. Dense and largely waste-free, though 'Cite amira_url' is a fragment whose referent is unclear.

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 read tool with no output schema, the description covers sort order and the three output modes (summaries, per-page citations, export file). Pagination/limit behavior is left entirely to the schema, but the core invocation-affecting behavior 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 high (79%) and the description still adds meaning beyond it: keyword reaches PDF text and returns match snippets, citation_format yields per-page citations, and export collapses every match into one file link. These clarify the interaction between parameters rather than restating field 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?

The description names the resource (bibliography/publications) and the operation (AND-filtered search, newest first), which is more specific than the title 'Search publications'. It narrows scope usefully but does not explicitly distinguish itself from siblings like search, search_research_items, or list_publication_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?

There is no explicit statement of when to use this tool versus alternatives, nor any exclusions. The schema points at list_publication_facets for discovering type values, but the description never routes the agent to siblings such as compare_collections or get_publication.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower. The description adds real behavioral context beyond that: filters combine with AND, empty results have a diagnosable cause, and export switches the response from rows to a file link rather than filtering differently.

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 purpose. The middle sentence on AND semantics and empty results is high-value; the export sentence is brief and earns its place.

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

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

For a 21-parameter read-only search with no output schema, the description covers the most consequential gotchas (AND logic, export mode, empty-result diagnosis). Return shape and pagination are left to the schema, which documents limit/offset, so nothing critical 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 95% with 21 documented parameters, so the schema carries nearly all parameter meaning. The description only gestures at the filter set and the export mode ('export links all matches as a file'), adding little syntax or constraint detail 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+resource ('Search digitised research items'), which clearly separates it from sibling searches like search_persons, search_publications and search_videos. It does not name any alternative directly, but the resource noun is distinct enough for disambiguation.

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 explains the AND-combination of filters and what empty results imply (relax a filter, or use a stored place name), which is genuinely useful usage context. However, it gives no explicit when-to-use vs. alternatives — nothing tells the agent when to prefer this over search or get_research_item.

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

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

Annotations cover safety profile (readOnly, idempotent, non-destructive, not open-world). The description adds that text-only hits include snippets and full transcripts require get_video with opt-in. This is useful context about output behavior, but it does not disclose other traits like pagination, rate limits, or whether results are ranked. With annotations already handling safety, this addition is moderate value.

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

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

The description is two concise sentences, front-loaded with the core purpose, no wasted words. It efficiently conveys the search scope and a key behavioral note.

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 and eight parameters with high schema coverage, the description provides sufficient context: it identifies the tool's domain, notes snippet vs. full transcript behavior, and points to get_video for full transcripts. It lacks explicit guidance on when to choose this over other search tools, but overall it is complete for an agent to understand and invoke the tool 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 88%, with clear descriptions for most parameters (limit, keyword, speaker, language, year_from/year_to, playlist). The description does not elaborate on parameter meanings beyond what the schema provides. Therefore, the baseline of 3 is appropriate, as the schema already does the heavy lifting.

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

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

The description states a specific verb+resource: searching video metadata and transcripts. It clarifies the content scope (metadata, transcripts, snippets), distinguishing it from generic text search tools. However, it does not explicitly differentiate from sibling search tools like search_podcasts or search_publications, leaving some ambiguity for an agent that must choose among many search_* tools.

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

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

The description implies usage for searching videos but gives no explicit when-to-use or when-not-to-use guidance against alternatives such as get_video or search. It does note that full transcripts require get_video with opt-in, which hints at a limitation, but lacks clear routing instructions (e.g., when to use search_videos vs. get_video directly).

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