IARCCUM Archive of Anglican-Roman Catholic Dialogue

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral information beyond the annotations: results rank exact protocol matches ahead of partial matches, and only public documents are returned.

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

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

A single front-loaded sentence with zero filler. The core action comes first and the ranking behavior 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?

For a read-only, closed-world search tool with rich annotations and full schema coverage, the description covers the essentials plus result-ordering behavior. It does not mention pagination semantics for offset/limit, but those are fully described in the schema, so the gap is minor.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema. The description reinforces the partial-match nature of the protocol parameter but adds no syntax, format, or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

The description gives a specific verb and resource (find public documents) scoped to archive protocol numbers, which sets it apart from the generic search_documents sibling. It stops short of naming that sibling explicitly, so differentiation 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?

Usage is implied by the protocol-number scoping, but there is no explicit when-to-use guidance, no exclusions, and no pointer to search_documents for non-protocol lookups. An agent must infer the boundary itself.

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 safety profile is covered. The description still adds real context beyond them: only 'released' documents are retrievable and only 'public items' are returned, which tells the agent about access scope. It does not say what happens when the ID is missing or unpublished.

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

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

One sentence, front-loaded with the verb and the resource, zero filler. Every clause earns its place by narrowing scope.

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 one-parameter read tool with annotations covering safety, this is nearly complete, and the description even sketches the return shape (metadata plus public items) despite no output schema. The only gap is behavior on missing or non-released IDs.

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

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

Single parameter with 100% schema description coverage ('IARCCUM document ID', integer, minimum 1), so the schema does the heavy lifting and the baseline is 3. The description adds no format or lookup semantics 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?

Specific verb (Return) plus resource (structured metadata and public items of one IARCCUM document), with scope words 'one' and 'released' that distinguish it from the plural search siblings. It does not name an alternative tool explicitly, so it stops short of the 5 benchmark.

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

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

Usage is only implied: an agent can infer this is the fetch-by-ID tool and search_documents/find_documents_by_protocol are the lookup tools, but neither the condition nor the alternatives are stated. No prerequisites or 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds a genuine data-access disclosure: private contact fields are excluded, so the agent knows the response is redacted. It also hints at the returned structure (hierarchy and relationship data). It does not mention error behavior for a missing ID.

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

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

Two tight sentences that front-load what is returned and then disclose the redaction constraint. Nothing is wasted.

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

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

With no output schema, the description carries the burden of describing the return, and it does so at a high level (public authority record, hierarchy, relationships, private fields excluded). A single-parameter read tool is adequately covered; only the not-found behavior is unspecified.

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 the single id parameter documented as an IARCCUM name authority ID. The description adds no meaning beyond that baseline, so a 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 specific verb and resource: 'Return one public authority record' with the scope 'one' distinguishing it from the sibling search_names. However, it never names search_names or any alternative, so the differentiation is implicit 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?

There is no statement of when to use this tool versus search_names or the other siblings. The word 'one' implies an ID-based lookup, but the agent must infer that from the required id parameter rather than from the description.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds useful scoping—only 'public' documents and only explicit links via the relationship table—but says nothing about ordering, deduplication, or result shape.

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

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

A single front-loaded sentence with zero filler; the scoping constraint ('explicitly linked', 'public') is stated up front and nothing is redundant.

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 not indicate what a returned related document contains or whether relationship metadata is included. Annotations and the schema cover safety and inputs, so what remains is a moderate gap around return semantics.

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

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

Schema description coverage is 100%, so both parameters (id, limit) are fully documented in the schema. The description adds no syntax, format, or filtering detail beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a specific verb (Find) and resource (public documents) with a clear scope qualifier: 'explicitly linked ... in the archive relationship table.' This distinguishes it from text-based siblings like search_documents, though it does not name any sibling directly.

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

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

The description implies the use case (finding related docs) but gives no explicit when-to-use condition, no prerequisites, and no routing guidance versus alternatives such as get_document or search_documents.

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 safety is covered. The description adds one useful behavioral fact not in the annotations: embargoed records are excluded from results. It says nothing about result ordering, pagination depth, or rate limits, so with annotations present a 3 is appropriate.

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

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

Two tight sentences with no filler, and the core capability is front-loaded before the embargo constraint. Every sentence earns its place.

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

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

With full schema coverage, no output schema, and annotations covering safety, the definition is nearly complete for a keyword-search tool. The remaining gap is minor: nothing about result ordering or how limit/offset interact in practice.

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

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

Schema description coverage is 100%, so each of the seven parameters is already documented with type, bounds, and format (e.g., date bounds as YYYY/YYYY-MM/YYYY-MM-DD). The description restates the query surface (title, description, full text) but adds no syntax or matching semantics beyond the schema, 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?

States a specific verb and resource ('Search ... documents') and names the searchable fields (title, description, indexed full text), which sets it apart from search_events/search_names/search_organisations. It does not distinguish itself from the closest sibling find_documents_by_protocol, 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 guidance and no mention of alternatives such as find_documents_by_protocol or get_document. The only scoping statement ('Embargoed records are never returned') limits results but does not help the agent choose this tool 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is fully covered externally. The description adds only the set of searched fields; it says nothing about result ordering, ranking, empty-result behavior, or pagination semantics beyond what the schema states.

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 searchable-field detail is the most useful information and comes first.

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

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

For a read-only search with full schema coverage and no output schema, this is minimally adequate. It still omits how results are ranked or returned and offers no guidance on combining the free-text query with the date range, leaving slight ambiguity for the agent.

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

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

Schema coverage is 100%, so the limit/offset/date bounds are already documented. The description adds genuine value the schema lacks by naming the fields matched (title, location, description, participants), clarifying what 'query' actually searches.

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

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

States a specific verb (search) and resource (events), and enumerates the searchable fields. This distinguishes it from siblings like search_documents or search_names by resource, though it never names those siblings explicitly.

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

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

The description gives no when-to-use guidance, no prerequisite conditions, and no routing to alternatives such as search_documents. 'Optional dates' implies date filtering but leaves the agent to infer when that matters.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond that – no mention of pagination limits, whether results are ranked, or what happens with partial matches. For a read-only search with full annotation coverage, the bar is lower, but the description adds nothing beyond the safety 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?

One efficient sentence that front-loads the core action. It is compact, though the long enumeration of identifier types makes it slightly dense and could be structured as a list. No wasted words.

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

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

For a simple read-only search with full parameter documentation and complete annotations, the description is adequate but leaves gaps: no sibling differentiation, no return value hints (no output schema), and no guidance on result ranking or pagination behavior. It is minimal viable.

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% (limit, offset, query all documented). The description adds marginal value by naming the identifier types that query accepts, but the schema already states 'Name, acronym, or external authority identifier'. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource: searching person and named-body authority records. The description enumerates searchable identifier types (ORCID, ISNI, LCNAF, VIAF, Wikidata), which is precise. However, it does not distinguish itself from sibling tools like get_name or other search_* tools, so and agent cannot route between search_names and get_name from this text alone.

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

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

No when-to-use guidance or exclusions. The description enumerates searchable fields but never says when to use search_names versus get_name, or how it relates to the other search_* siblings. An agent must infer usage entirely.

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 the safety and idempotency profile is covered. The description adds one useful behavioral constraint, that only IARCCUM-marked authority records are searched, but says nothing about result ordering or return shape.

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

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

A single front-loaded sentence with zero filler. Nothing is wasted and the scoping qualifier follows immediately after the verb and resource.

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 three-parameter search with full schema coverage and safety annotations, most needs are met. However, with no output schema, the description should indicate what a result contains or how pagination behaves, which it omits.

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 query, limit, and offset all documented in the schema. The description adds no parameter syntax or format detail beyond the schema, so 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?

States a clear verb (Search) and a specific, scoped resource (authority records marked as IARCCUM organisations/fonds). It does not differentiate itself from siblings like search_names or search_documents, leaving the agent to infer the distinction from the resource qualifier alone.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The agent must infer usage from the tool name and the 'IARCCUM' scoping phrase.

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