USVI Public Records

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 description doesn't need to restate safety. It adds real value by disclosing the shape of the report (four distinct metrics, including a staleness comparison against the published archive) and by explaining how to interpret an empty search result. It says nothing about cost, latency, or whether the numbers are cached, which keeps it below a 5.

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

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

Two sentences, front-loaded with the primary metric list, and each clause maps to a distinct returned number rather than padding. The first sentence is long and runs four items together, which costs a little readability but not substance.

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 parameters and no output schema, the description carries the burden of explaining what comes back, and it does so by naming the four reported measures plus the freshness comparison. Exact field names and units are unspecified, but an agent has enough to decide to call it and to interpret the result.

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

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

The tool takes zero parameters and schema coverage is 100%, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies a single parameterless call.

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 ("Reports") and enumerates four concrete facets of the resource: searchable document count, text volume covered, per-filter archive visibility, and index-vs-published-archive freshness. No sibling tool (search, fetch, get_document, list_collections) produces coverage or freshness metadata, so the purpose is unambiguous even without naming an alternative.

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

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

"Use for questions about what the archive covers or how current it is" gives clear positive conditions, and "or to judge how much an empty search result means" supplies a non-obvious secondary use case tied to sibling tools. It stops short of stating when not to call it (e.g., that it is not a substitute for search), so it misses the explicit-exclusion bar for 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 establish read-only, idempotent, non-destructive behaviour, so the bar is lower. The description still adds real value beyond them: the 40,000-character cap, the next_offset continuation token for truncation, and the disclosure that text is returned fenced as untrusted data (a prompt-injection safety signal an agent needs to know).

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

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

Three sentences, all earning their place: purpose and payload first, usage routing second, trust-boundary caveat last. Nothing is redundant and the most important constraint 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?

With one parameter and no output schema, the description carries the burden of explaining the return shape, and it does: catalogue record, text excerpt, and pagination token. Minor gap is that it does not describe what the catalogue record contains or whether further pages are fetched with the same id plus next_offset.

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 id parameter is fully documented in the schema with format and example, so the schema does the heavy lifting. The description only restates that the id is an archive id, adding no new syntax or constraint information; 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 specific verb+resource: retrieve one document by archive id, and specifies the payload (catalogue record plus up to 40,000 chars of extracted text). It does not clearly differentiate itself from the sibling tools get_document and get_document_text, which appear to overlap heavily with this behaviour.

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

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

"Use to read a document found by search" gives one clear usage context and implicitly points at the search sibling as the discovery step. However, it offers no exclusions and says nothing about when get_document or get_document_text would be preferred, so the routing decision against those siblings 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 burden is lifted. The description adds genuine behavioral context beyond them: the exact field set returned and the negative guarantee that no document text is included, which prevents a common mis-call. It stops short of any note on missing/deleted records or error behavior, keeping it from a 5.

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

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

Two tight sentences: the payload contents come first, then the usage and the boundary against alternatives. No filler, no repetition of the title, and the most decision-relevant information (what it does not return) is placed where it will be read.

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

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

There is no output schema, so the description compensates by enumerating the returned fields, and it closes the one dangerous ambiguity (text availability) for a single-parameter read tool. Nothing an agent needs to invoke this 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 100% with a single required parameter whose format is fully documented ('LF- followed by 12 characters, e.g. LF-6e02fd648a12'). The description says nothing about lf_id, so the schema does all the work and 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?

Names a specific verb and resource ('full catalogue record for one document') and enumerates exactly what the record contains (collection, entity, dates, page count, SHA-256, extraction status, source URL). It also distinguishes itself from get_document_text and fetch by stating it carries no document text, so an agent can pick it apart from siblings without opening any schema.

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

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

Gives an explicit use case ('check a document's provenance or details') and an explicit exclusion with the alternatives named ('It holds no document text; get_document_text and fetch return that'). The routing decision between this tool and its text-returning siblings is fully resolved in 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 read-only, idempotent, non-destructive behavior, and the description adds real context beyond them: the pagination contract (has_more always present, next_offset when truncated), blank-line normalization, and that text is returned fenced as untrusted data from scanned/filed sources.

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

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

Front-loads resource and windowing, then covers pagination, normalization, and trust marking in four tight sentences with no filler. Every clause 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?

No output schema exists, and the description compensates by naming the return fields (text window, has_more, next_offset) and the untrusted-data fence. An agent can paginate and safely interpret the result without further information.

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 all three parameters are already documented, including offset as a next_offset value. The description restates the window size and default rather than adding syntax or format meaning 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?

States a specific verb and resource ('The extracted text of one document') plus the windowing scope, so the agent knows exactly what is returned. It does not explicitly distinguish itself from the sibling get_document (metadata vs. text), which keeps it from 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?

'Use to read a long document in order' gives clear usage context and the hearing-transcript example conveys the intended scale. No explicit when-not or named alternative (e.g., get_document for metadata) is offered.

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 closed-world behavior, so the safety profile is covered. The description contributes beyond that by disclosing that results include document counts, which is the only return-shape information available since no output schema exists.

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

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

Two short sentences with the resource first and the routing guidance second; no filler and nothing duplicated from the schema 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?

For a no-parameter, read-only list tool with no output schema, the description covers what comes back (collections with counts) and why you'd call it. Minor gaps such as ordering or pagination are not addressed but are unlikely to matter at this scale.

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

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

Zero parameters means there is little to document, so the baseline is high. The description still adds value by tying the tool's output to a parameter on another tool (the collection filter on search_records), clarifying how the data is consumed.

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-resource pair ('The collections in this server') plus a statement of what the response contains ('with document counts'). It is clearly distinguishable from siblings like archive_stats or search_records because it returns the collection vocabulary rather than statistics or 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?

Gives two concrete use cases: browsing what the archive holds, and obtaining valid values for the collection filter on search_records. This is real routing guidance, though it never says when to prefer archive_stats over this for a high-level overview.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantive beyond-schema behavior: a hard cap of 10 results, the per-document fields returned, that the index covers full text plus catalogue records, and that withheld/withdrawn documents are absent rather than filtered. That last point materially shapes how an agent should interpret empty or thin results.

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

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

Front-loads purpose and result shape in the first sentence, then routing, then scope, then exclusions. The enumerated newspaper names are long but earn their place by preventing false-negative conclusions about the archive's holdings.

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 single-parameter search tool with no output schema, the description supplies the result cap, the returned fields, index coverage, and explicit negative scope. Nothing an agent needs in order to call it or interpret its output 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?

Only one parameter and schema coverage is 100%, so the schema already documents the query string including the quote-a-phrase behavior. The description echoes 'keyword or phrase' but adds no new syntax or format 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?

States a specific verb and resource ('Find U.S. Virgin Islands public records'), names the scope (full extracted text plus catalogue records), and previews the return shape. It explicitly distinguishes itself from sibling search_records, so an agent can choose 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?

Gives an explicit use case ('quick lookup') and the alternative plus its differentiator ('search_records adds filters, match reasons and paging'). It also states what is not covered — newspapers on a separate connector and unpublished material — which is exactly the when-not guidance an agent needs.

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, closed-world and non-destructive, so the safety profile needs no restating. What the description adds beyond them is result-shape behavior: the tier definitions, the absence of a numeric relevance score, the partial-match fallback with a 'matched' list, and the note that withheld/withdrawn documents are simply absent. That is substantive extra context.

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

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

Front-loaded with purpose and trigger before the longer tier taxonomy. The tier block is lengthy but justified because there is no output schema to explain result structure; nothing reads as filler, though the passage could be tightened slightly.

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?

Nine parameters, no output schema, and no enum constraints, yet the description covers ranking tiers, match explanation fields, paging context, partial-match behavior, scope exclusions, and coverage limits. An agent has everything needed to call it and interpret the result correctly.

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

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

Schema coverage is 100%, so parameter documentation is already carried by the schema. The description still contributes semantics the schema does not: filters use the website's own facet vocabulary, and search covers extracted full text as well as catalogue records, which tells the agent what 'query' actually matches against.

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?

Says precisely what it does: searches the archive's full extracted text plus catalogue records, with named filter dimensions (collection, entity, content type, island, year). The one gap is that it never distinguishes itself from the sibling 'search' tool, leaving the agent to infer the split from the filter list 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?

Gives a positive trigger ('when a question needs narrowing, paging, or the reason each document matched') and an explicit exclusion with a pointer elsewhere ('newspapers ... on its separate newspaper connector'). It stops short of routing among the sibling tools search, fetch, and get_document_text, which the agent must guess at.

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