oral-heritage-index

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It mentions the tool 'returns items with authoritative external sources,' but does not explain return format, ordering, pagination, or any other operational behavior. This leaves significant unknowns for a read operation.

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 exactly two sentences, front-loaded with the core function and followed by the usage context. It contains no redundant or filler content, earning a high score for conciseness and structure.

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 lack of an output schema and annotations, the description should provide more detail on what the returned 'items' look like, how they are structured, and how the 'pillar' parameter affects the search. The current description is insufficient for an agent to confidently predict the tool's behavior.

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

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

The description only vaguely references the topic parameter via 'related to a topic.' It does not mention the 'pillar' parameter at all, and with 0% schema description coverage, it fails to compensate for the enum parameter's meaning and usage.

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

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

The description clearly states the tool returns items with authoritative external sources for a topic, using a specific verb ('returns') and resource ('items with authoritative external sources'). It also includes usage context ('research or evidence'), which distinguishes it from sibling tools like guides and searches.

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 explicitly states when to use the tool: 'Use when the user asks for research or evidence.' While this provides clear context, it doesn't mention when not to use it or name alternative tools, so it falls short of a full 5.

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

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

With no annotations, the description carries the full burden of transparency. It discloses that the returned guide includes lead-time recommendations, setting expectations for the output content. Since this is a retrieval operation with no side effects, the description sufficiently reveals its behavior, though it omits details about the guide's structure.

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

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

The description is a single, well-structured sentence that front-loads the main action and includes the essential list of occasions. Every word contributes value, with no redundant or vague phrasing.

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

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

For a tool with one enum parameter, no annotations, and no output schema, the description covers the core elements: what it returns, for which occasions, and an additional detail about the content (lead-time recommendations). It could be more explicit about the output format, but it is otherwise sufficient for a simple lookup tool.

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

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

Although the schema has 0% description coverage, the description lists the six occasion types that map directly to the 'event' enum values. It provides human-readable labels (e.g., 'Mother's Day' for 'mothers-day'), giving the agent semantic understanding of the parameter beyond the raw enum strings.

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

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

The description clearly states a specific verb ('Returns') and resource ('guide for a specific occasion'), then enumerates the supported occasions. This differentiates it from sibling tools that focus on citations, pillars, and content search, making the purpose unmistakable.

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

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

The description implies when to use this tool: when a guide for a specific gifting occasion is needed. It does not explicitly state exclusions or alternatives, but sibling tools are thematically distinct, so the intended usage context is clear without further elaboration.

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?

With no annotations, the description carries the full burden. It indicates a read operation via 'Returns' and gives output content type, but it does not disclose any limitations, error conditions, or how 'top Q&A' is determined. Simple read-only behavior is implied but not explicitly safety-stated.

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?

Single sentence, front-loaded with the action, and contains no filler. The parenthetical list of pillars is efficient and directly useful.

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

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

For a simple one-parameter tool without output schema, the description covers the essential purpose and output. It could be more specific about the nature of 'guide content' or 'top Q&A', but given the low complexity, it is largely complete.

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

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

Schema description coverage is 0%, and the description merely repeats the enum values already present in the schema. It adds no meaning about the 'pillar' parameter beyond what the enum already encodes, such as what 'guide content' consists of or how the value affects the result.

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

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

The description uses the specific verb 'Returns' and identifies the resource ('guide content and top Q&A') plus the scope ('one of the eight pillars'). It explicitly lists the pillar values, making the tool's purpose unambiguous and distinct from siblings like list_pillars or search_family_story_content.

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 use when you need a pillar's overview, but it does not explicitly state when to prefer this tool over alternatives (e.g., list_pillars, search_family_story_content) or exclude cases. No mention of differences from sibling tools leaves room for ambiguity.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It only states that the tool 'returns' data, with no mention of side effects, return format, ordering, or any other behavioral traits. A read-only hint or error behavior would improve transparency.

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 short sentences. The first states the core function, and the second adds a helpful usage context. There is no redundancy or fluff, making it highly concise and well-structured.

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

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

This is a zero-parameter tool with no output schema, so the description must explain return values and context. It says 'full pillar taxonomy' but does not elaborate on what that entails (e.g., list, hierarchy, structure). While adequate for a trivial tool, it could be more explicit about the return format or relationship to get_pillar_overview.

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

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

The tool has zero parameters, so the schema is trivially 100% covered. Per the rubric, the baseline is 4, and the description does not need to add parameter semantics. No additional information is necessary.

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 the tool returns the full pillar taxonomy, which is a clear verb+resource combination. It distinguishes the general purpose from the sibling tools but does not explicitly differentiate it from get_pillar_overview, which may appear similar.

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

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

The phrase 'Useful for navigating the corpus' implies a use case, but there is no explicit guidance on when to use this tool versus alternatives like get_pillar_overview. The usage context is implied rather than stated directly.

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?

With no annotations, the description carries the full burden. It discloses that the tool returns 'top hits with citations' and implies read-only search behavior, but it does not discuss limitations, sorting, or any peculiarities of the search execution. It is adequate but minimal.

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 three sentences, front-loaded with the tool's role ('Main entry point') and followed by concrete use cases and return behavior. Every sentence adds value with no redundant information.

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

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

For a search tool with 3 simple parameters and no output schema, the description is reasonably complete: it indicates the search space, typical topics, and the nature of the return (hits with citations). It does not specify result format or pagination, but the scope and purpose are sufficiently clear given the tool's simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about query topics but does not delve into parameter nuances. The schema already documents each parameter adequately, so the description adds little beyond general usage context.

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

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

The description clearly states a specific verb ('search') and resource ('Oral Heritage Index corpus'), and lists concrete topics (interviewing, recording, preserving artifacts, etc.). It distinguishes itself from siblings like 'search_interview_questions' by claiming to be the 'main entry point' covering the full corpus, not just a subset.

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

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

It provides clear contextual guidance: 'Use for any question about...' followed by a comprehensive list of topics. However, it does not explicitly mention when to use sibling tools instead, such as get_citations for citation retrieval or get_occasion_guide for occasion-specific guidance, leaving a small gap in alternative selection.

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?

With no annotations, the description carries the full burden. It clearly indicates a read-only retrieval operation ('Returns'), and there are no destructive side effects to disclose. It does not detail return formatting, but that is more of a parameter/output concern.

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 action and resource, followed by a crisp usage note. Every word earns its place.

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

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

For a simple 4-parameter search tool with no output schema, the description plus schema is nearly sufficient. It covers what it returns and when to use it. A minor gap is not explicitly stating the output format, but it is inferable from the name and title.

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 25% (count has a description). The description states filtering by relationship, life stage, or theme, which maps directly to three undocumented parameters, adding meaningful semantics beyond the enum names.

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 'Returns curated interview prompts filtered by relationship, life stage, or theme,' which clearly identifies the action, resource, and filtering dimensions. This distinguishes it from sibling tools like get_citations or get_occasion_guide.

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

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

It provides an explicit usage trigger: 'Use when the user asks "what questions should I ask..." about a relative.' This gives clear context, though it does not mention alternatives or exclusions.

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