Video History Project

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is established. The description adds value by specifying exactly what the description will cover (searchable text, filters, citation practices, response limits), which gives the agent a clear expectation of the content without contradicting 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?

The description is a single sentence that front-loads the core action ('Describe the Video History Project collection') and then enumerates the key aspects covered. It is concise and avoids redundancy, though it could be slightly more structured by separating the usage hint, but it remains efficient and readable.

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 tool has no parameters and an output schema exists (which would define the return structure), the description sufficiently covers what the agent needs to know to invoke it correctly: the scope of the description (collection, searchable text, filters, citation practices, response limits) and when to use it (beginning research). No critical information is missing for this low-complexity 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?

The tool has zero parameters, so the description has no parameter semantics to clarify. According to the baseline rule for 0-parameter tools, a score of 4 is appropriate since there is nothing to explain beyond what the schema already indicates (an empty object).

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

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

The description clearly states the tool's purpose: to describe the Video History Project collection, including its searchable text, filters, citation practices, and response limits. This is a specific verb ('describe') applied to a distinct resource, and it differentiates itself from sibling tools like search_records or get_record, which retrieve or manipulate data rather than provide an overview.

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

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

The description provides a usage context by stating it is 'useful when beginning research,' which implies it is an entry point for orientation. However, it does not explicitly mention when not to use it or compare it to alternatives like search_records or list_terms. The guidance is present but not thorough.

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 mark the call as read-only and non-destructive; the description adds real behavioral detail by capping input size at 25 and disclosing per-item error behavior for missing publication metadata. This is more than redundant with the structured 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?

Two dense sentences deliver scope, options, constraints, and target-selection guidance with no filler. Every clause contributes new functional information, and the most important disambiguation ('choose page…') is placed at the end as a decision rule.

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 export tool with an output schema already available, the description covers the essential invocation decisions, edge-case behavior, and target-selection logic. There is no obvious missing piece an agent would need to successfully 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?

With 0% schema description coverage, the description carries the full parameter burden, and it covers all three parameters: IDs (1–25 VHP IDs or URLs), format (text or ris), and target (publication or page, with page's purpose clarified). This provides enough semantic information for an agent to construct correct calls.

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 ('export citations') with a clear resource scope (1–25 VHP IDs or URLs) and defines the two dimensions that shape the output (format and target). This is unmistakably distinct from read/search/collection siblings and leaves no doubt about what the tool produces.

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 actionable context for choosing the 'page' target ('choose page to cite a biography or history page') and warns about the failure mode when publication metadata is missing. It does not explicitly name sibling alternatives, but none of the listed siblings are citation-export competitors, so the contextual guidance is sufficient.

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 and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it resolves old addresses locally, returns a section of existing text, requires following content.nextOffset for complete text, and explicitly states that linked scans are not read. This goes beyond the annotations and helps the agent understand the tool's behavior and limitations.

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

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

The description is compact and front-loaded: it opens with the core action and resource, then adds the most important behavioral notes (local resolution, return contents, section default, pagination, scan limitation). Every sentence earns its place, and there is no repetition of schema or annotation 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?

The tool has an output schema, so return values are already structured. The description covers the key operational details: identifier types, section selection, pagination via nextOffset, and the scan limitation. It does not mention 'limit' or 'version' semantics explicitly, but the pagination guidance implies their role. For a read-only tool with an output schema, this is nearly 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%, so the description must compensate. It does: it explains that 'id' can be a VHP record ID or VHP URL, that 'section' defaults to 'body' and other sections come from 'sections', and that 'offset' pagination should use content.nextOffset with the same section and version. It does not explain 'limit' or 'version' in detail, but the pagination guidance covers the key semantics. This is strong compensation for the schema's lack of descriptions.

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

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

The description states a specific verb ('Read') and resource ('public VHP record'), and specifies the two accepted identifiers (ID or VHP URL). It also distinguishes itself from siblings by noting it resolves old addresses locally and returns metadata, source links, citations, and a section of existing text. This is a clear, specific purpose statement that an agent can act on.

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 clear context on how to use the tool: default section is body, choose other sections from sections, and follow content.nextOffset with the same section and version for complete text. It also states a limitation ('Linked scans are not read'). However, it does not explicitly say when to use this tool versus alternatives like search_records or get_related_records, so it misses explicit exclusions.

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

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

Annotations already declare readOnlyHint and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral nuance beyond annotations: results are research leads rather than evidence, and the endpoint may return nothing if the index is empty or suggestions have been disabled.

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 sentences with no filler. The core action is front-loaded, and the clarifying caveats each add essential information about result interpretation and empty responses.

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 return structure is already covered. The description explains the key empty-case and interpretive caveat, but it is still missing parameter-level guidance for 'limit' and general selection guidance relative to sibling 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 0%, so the description must compensate for undefined parameters. It implicitly explains that 'id' refers to a public record, but it says nothing about 'limit,' its default, or how it affects returned suggestions.

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 a specific verb-resource pair, 'Get the site's existing similarity suggestions for a public record,' which clearly identifies what the tool returns. It also distinguishes the operation from sibling tools like get_record and search_records by focusing on precomputed similarity suggestions.

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 useful interpretive context by saying these are 'research leads, not evidence of a historical relationship,' which implies when not to rely on it. However, it does not explicitly name alternatives or give concrete conditions for choosing this tool over siblings like search_records.

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 (readOnlyHint and destructiveHint), lowering the burden. The description adds value by specifying response content (exact keys, display labels, counts) and the pagination behavior ('Follow nextPage'). No contradiction with 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 terse sentences with no filler; the purpose is front-loaded and the workflow/pagination guidance is compact. 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?

The tool is simple, has an output schema, and the description covers purpose, key parameters, return content, and pagination. The only notable gap is that `page` and `limit` semantics are left implicit, though defaults and standard pagination conventions mitigate this.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains `field` ('author or subject') and `query` ('part of a name'), but leaves `page` and `limit` to their defaults and conventional meaning without explicit semantics.

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 ('catalog author or subject filter keys'), and adds the distinguishing detail of partial-name lookup. It clearly separates this from search_records by noting the returned keys are meant to be used there.

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

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

Provides workflow guidance: follow nextPage and pass a returned key into search_records, which positions the tool relative to its obvious sibling. It does not enumerate exclusions, but the context is clear enough for an agent to select it for key discovery.

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

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

Annotations already declare a read-only, non-destructive, closed-world operation. The description adds useful behavioral detail: empty query browses, excerpts label their source, and nextPage must be followed for pagination. No contradiction with 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?

The description is five concise, purposeful sentences, front-loading the core purpose and immediately adding browse and filter behavior. Every sentence adds distinct operational value without redundancy.

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

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

For a read-only search tool with an output schema present, the description covers the essential invocation context: vocabulary sources, type source, year range, pagination, and source-excerpt provenance. It also warns about quoting and directs to get_record, making it complete for safe and correct use.

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 0% schema description coverage, the description carries the burden for parameter meaning. It maps query to 'words or quoted phrases', author/subject to controlled keys, type to describe_collection, and 'recorded years' to the to/from range parameters. It omits explicit mention of limit and page, though 'Follow nextPage' implies pagination.

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

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

The description clearly identifies the resource ('public VHP records'), the action ('Search'), and the search syntax ('by words or quoted phrases'), while also noting the empty-query browsing behavior. It is distinct from siblings like get_record (retrieval) and list_terms (vocabulary) by focusing on generalized search.

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

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

It explicitly instructs combining controlled vocab from list_terms and type from describe_collection, and advises reading get_record before quoting, which guides tool selection. It doesn't explicitly state when to prefer export_citations or get_related_records, but the quoted-source warning implies get_record for full citations.

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