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

No annotations are provided, so the description carries the full burden. It usefully discloses the limit range (1 to 50) and that filetype acts as a filter, but says nothing about ordering, pagination beyond the limit cap, or what happens with an unknown category. For a low-risk read tool this is adequate but thin.

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 front-loaded sentence stating the operation plus a compact Args block. Every line carries information; no 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?

With only 3 parameters, an output schema present, and all parameters explained, an agent has enough to invoke it correctly. Minor gaps remain around result ordering and behavior past the 50-item cap.

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 0%, so the description must compensate, and it does: it explains the 'Category:' prefix is optional, gives the limit range 1-50, and supplies the filetype vocabulary (bitmap, drawing, audio, video) that the schema lacks. The limit default (20) is not mentioned, keeping it short of a 5.

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 ('List the files in a Commons category') and anchors it with a concrete example ('Mosby's Rangers'). It is clearly distinct from siblings like commons_search (finding) and commons_file_info (metadata for one file).

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 by naming what it lists, but never says when to prefer it over commons_search or commons_file_info, nor does it mention any prerequisites. No exclusions or alternative-routing guidance is present.

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 provided, so the description carries the full burden. It discloses the returned fields, which implicitly signals a non-mutating metadata read, but it says nothing about authentication, rate limits, failure modes (e.g. missing file), or whether the lookup is exact-match or normalized.

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 front-loaded sentence listing the returned fields, followed by a compact Args block for the sole parameter. Nothing is padded and the essential information 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?

An output schema exists, so the description need not explain return structure, yet it usefully previews the returned fields and covers the only parameter's format. The main remaining gap is the absence of any error/empty-result behavior for a nonexistent 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 0%, but with a single parameter the description supplies the key semantic detail the schema lacks: the title is a file name that may be given with or without the 'File:' prefix. That normalization rule is exactly the kind of information an agent needs and would not get from the bare string type.

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 (one Commons file) and enumerates exactly what is returned: licence, author, description, categories, original size. This is clearly distinguishable from siblings like commons_search and commons_category_members, which operate on collections rather than a single file.

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 singular 'one Commons file', which suggests it is the detail lookup paired with commons_search, but no sibling is named and there is no explicit when-to-use or when-not-to-use guidance. Adequate but leaves routing 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?

With no annotations, the description carries the full burden, and it does disclose a useful behavioral trait: each record carries the licence read from the file metadata, and maps are matched by the word 'map' in the title. It says nothing about auth needs, rate limits, pagination, or result ordering, which leaves real gaps for a no-annotation 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?

The purpose is front-loaded in one sentence followed by a structured Args block, and there is little waste. The terse arg strings are slightly cryptic (e.g. bare value lists) but the structure 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 simple search tool with an output schema already covering return shape, the description is nearly complete: purpose, all four params and their value domains are covered. The missing pieces are usage routing versus siblings and behavioral constraints like pagination, which matter less because an output schema exists.

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, and it does: it documents all four parameters, gives the limit range (1 to 50), enumerates the filetype values, enumerates the kind values, and notes the map-matching quirk. This is strong compensation, though it omits defaults and the interaction between filetype and kind.

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 opens with a specific verb+resource ('Search Wikimedia Commons files'), which an agent can distinguish from dpla_search, ia_search, nara_search and si_search on the resource alone. It does not explicitly differentiate itself from the Commons siblings (commons_file_info, commons_category_members), so it stops 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, no prerequisites, and no alternatives named. An agent gets no signal on when to prefer commons_search over commons_category_members or the other repository search tools; usage is only weakly implied by the tool 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?

With no annotations, the description carries the full burden and does well: it discloses the https/public-address fetch restriction, the provenance sidecar contents (source, URL, retrieval time, SHA-256, stated rights), the rights_warning behavior when rights.reuse is not free, and cache/overwrite semantics. It omits auth requirements, rate limits, and failure modes, so it stops short of 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?

Front-loaded with the action and side-effect, then an Args block that is dense and earns its place. Slightly verbose in the sidecar sentence but no filler; structure makes the contract easy to scan.

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?

Output schema exists so return values need not be restated, and the description still covers the important non-schema behavior: sidecar writing, rights warnings, URL restrictions, and per-parameter meaning. An agent has everything needed to invoke it 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 0%, so the description must compensate, and it does for all six parameters: source is enumerated (internet_archive, commons, dpla, nara, smithsonian), media_kind lists valid kinds, media_index default is explained, overwrite semantics are given, and max_mb's default and HERITAGE_MCP_MAX_DOWNLOAD_MB env override are documented.

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+scope: 'Download one original file from a record into the local cache and write a provenance sidecar.' The 'one original file' scope and the sidecar side-effect clearly separate it from sibling read tools like get_record, ia_get_item, or commons_file_info.

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 rather than stated: the description explains the media_index/media_kind selection interplay and overwrite behavior, which helps an agent call it correctly, but never says when to prefer this tool over siblings or what prerequisites (e.g., a prior search to obtain record_id) apply. No alternatives or exclusions are 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?

With no annotations, the description carries the full behavioral burden, and it does disclose the auth requirement (API key), which is genuinely useful and not present in structured fields. It says nothing about error behavior, rate limits, or what happens with an invalid/missing id, so it is only partially transparent.

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, front-loaded sentences with zero filler. The core action comes first and the prerequisite second.

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 single-parameter retrieval tool with an output schema present, the description covers the essential action and the auth prerequisite. The return shape is handled by the output schema, so the only real gap is the lack of id-format detail and sibling routing.

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 single parameter item_id has no schema-level documentation. The phrase 'by its id' hints that item_id is an identifier, but nothing about format, source, or example is added, so the description does little to compensate for the coverage 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?

States a specific verb and resource ('Get one DPLA item by its id'), which is enough for an agent to know it retrieves a single item rather than listing or searching. It does not explicitly distinguish itself from the sibling dpla_search, but the singular 'one item by its id' does imply the difference.

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 a prerequisite ('Needs DPLA_API_KEY') but no guidance on when to use this versus dpla_search, or when an item id is the right input. No alternatives or exclusions are named, so the agent must infer usage from the tool name alone.

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 and mostly does: it discloses the DPLA_API_KEY requirement and the non-obvious behavioral fact that DPLA indexes descriptions rather than item contents, plus a rights caveat. It omits rate limits, result-count limits, or behavior when no argument is supplied.

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?

Purpose and the scoping caveat are front-loaded, and the per-argument block is dense and each line carries a distinct semantic payload. It is slightly long, but with 14 undocumented parameters the list is justified rather than padding.

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 described, and the description instead supplies the missing essentials for this parameter-heavy search: auth requirement, query-vs-filter usage, result interpretation caveat, and rights handling. Nothing an agent needs to call it correctly is absent.

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 14 parameters, so the description must compensate and does — it documents each argument's meaning, gives date formats (YYYY or YYYY-MM-DD), a page_size range (1 to 100), sort_by field examples, enum-like values for type and kind, and clarifies that maps are images with the subject 'Maps'. This is far more than the bare schema titles convey.

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 opens with a specific verb and resource ('Search the Digital Public Library of America for items held by US libraries, archives and museums'), and the named repository clearly separates it from the many sibling search tools (ia_search, nara_search, si_search, commons_search) and from dpla_get_item. An agent can tell what this does and which corpus it targets without opening 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?

'Give a search term, any filter, or both' states the invocation precondition, and the note to follow `landing_url` and read `rights` gives clear post-search guidance. It does not explicitly name dpla_get_item as the follow-up alternative, so the routing advice stops just short of full when/when-not coverage.

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 provided, so the description carries the full burden. It discloses that the payload includes media files and rights, and the verb 'Fetch' implies a read-only operation, but it says nothing about auth, rate limits, error behavior for invalid source/record_id, or whether the fetch is 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?

Front-loaded one-sentence purpose followed by a compact Args block; no filler. Slightly redundant restating of parameter names already visible in the schema, but overall 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?

An output schema exists, so return values need not be re-explained, and the parameter documentation is solid. The gap is routing: with ~20 siblings including several source-specific 'get' tools, the description never says when this generic getter is preferable to nara_get_record/dpla_get_item/ia_get_item.

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 schema provides no enum for 'source', so the description does the heavy lifting: it enumerates the five valid sources and explains the id format for each source (IA identifier, Commons 'File:' title, DPLA id, NARA naId, Smithsonian id). That is substantially more than the schema offers, though it doesn't state what happens on an unrecognized source or mismatched id format.

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 ('Fetch one record') plus what the returned object contains (normalised shape, media files, rights). It does not, however, distinguish itself from the source-specific getters in the sibling list (nara_get_record, dpla_get_item, ia_get_item), so an agent can't tell from the description alone which getter to pick.

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: 'record_id: The id from a search result' hints that this follows a search, but there is no explicit when-to-use/when-not statement and no comparison against the numerous per-source getter 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?

With no annotations, the description carries the full burden, and it does disclose useful traits: matches wrapped in **, snippets with page numbers, and that the endpoint is experimental and may change. It omits auth requirements, rate limits, and any statement about result stability, so it is only partially transparent.

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 the core purpose, then usage context, then a compact Args block. No filler sentences, though the arg list is somewhat tersely formatted.

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 documentation is unnecessary, and all three parameters are explained. The experimental-endpoint caveat covers stability. Minor gap: no guidance on paginating through large result sets or handling the 50-hit cap.

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 0%, so the description must compensate, and it does: query is 'Words or a "quoted phrase"', hits is bounded to 1-50, and page is defined as 'Page number from 1'. This adds real meaning over the bare schema types, though default values (10 and 1) are left to 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 and resource ('search the OCR text inside Internet Archive books and reports') and adds scope ('with snippets and page numbers'). It is clearly distinguishable from siblings like ia_search, ia_read_text and ia_grep_text.

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 clear use context: 'This is the way to find a name, place or phrase inside a memoir, regimental history or official report.' That tells the agent when this tool is appropriate, but it never names an alternative tool or an exclusion condition, so routing among the ia_* siblings still requires 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses what content comes back (PDF, OCR text, page images), but says nothing about whether files are actually downloaded, permission/authentication needs, rate limits, or response size limits for large items.

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 front-loaded sentence with zero filler; the verb and resource lead, and the parenthetical enumerates return content compactly.

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 the return shape need not be documented, and for a single-parameter retrieval tool the description is close to sufficient. The remaining gap is the identifier's expected form, which neither schema nor description explains.

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?

There is one required parameter with 0% schema description coverage, and the description adds nothing about it — no identifier format, no example (e.g., an Internet Archive item slug), no statement that it must be an exact item id rather than a query. The single self-evident name does not fully compensate for the coverage 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?

States a specific verb (get) and resource (one item) and enumerates what the caller receives: metadata, rights, downloadable files. That distinguishes it from the sibling search tools (ia_search, ia_fulltext_search) and the text tools (ia_read_text, ia_grep_text), though it never names an alternative 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?

Usage is only implied: a caller with an item identifier who wants the item's metadata and files would reach for this. There is no statement of when to prefer it over ia_read_text or ia_grep_text, nor any prerequisite such as needing an identifier obtained from ia_search.

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 behavioral burden and does well: it discloses the in-memory fetch-and-cache behavior (performance trait), and that "the total is always reported" even when matches are truncated. It omits auth/rate-limit details, but for a read-only grep these are minor.

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 purpose sentence followed by a performance note, then a clean Args block. Every sentence earns its place with no 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 values needn't be explained, and all six parameters are documented. The only gap is the lack of explicit routing guidance versus sibling tools, which the description could have added.

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, and it does: it explains normalization behavior for the pattern (line breaks, repeated spaces, split hyphens), the meaning of the regex flag, the context range (0–1000), and the max_matches range plus total reporting. Every parameter gains meaning beyond the bare 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 first sentence states a specific verb ("Find every occurrence") and resource ("a word or phrase in an item's OCR text") plus the return shape ("with surrounding context and offsets"). This clearly distinguishes it from siblings like ia_read_text and ia_fulltext_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?

The description implies usage through "repeated searches of the same book are fast," suggesting it's for iterative querying of one item, but it never explicitly says when to choose this over ia_read_text or ia_fulltext_search. Usage context 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?

With no annotations, the description carries the full behavioral burden, and it does disclose two useful traits: the operation is offset/slice-based and is capped at 20,000 characters per call. However, it omits auth requirements, behavior when start is past the end of the text, whether the cap is enforced or truncated, and any error/pagination semantics.

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, zero filler, with the core capability front-loaded and the routing hint second. 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?

An output schema exists, so return values need not be explained. The description supplies the operation, the slicing mechanism, the size cap, and the recommended sibling workflow, which is sufficient for an agent to call this 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 0%, so the description must compensate for all three parameters. It conveys the offset concept and the 20,000-character ceiling, which maps to start/length, but never names the parameters, never mentions the length default of 4000 or start default of 0, and says nothing about the required identifier's expected form.

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 ('Read a slice of an item's OCR text') plus the mechanism ('by character offset') and a hard cap ('up to 20,000 characters at a time'). It does not explicitly differentiate itself from similar text-retrieval siblings like nara_extracted_text or si_get_content, so it stops 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?

Explicitly routes the agent to a prerequisite workflow: 'Use ia_grep_text first to find the offset you want.' That is clear when-to-use guidance tied to a named sibling. It gives no when-not or alternate-path guidance (e.g., when to use ia_get_item instead), keeping it below 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?

No annotations are provided, so the description carries the burden. It usefully adds Lucene query syntax and a noise caveat for 'kind: map', but does not disclose pagination limits beyond rows/page, auth requirements, rate limits, or return behavior. Output schema exists, so return values are partly covered elsewhere.

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?

Purpose and the sibling boundary are front-loaded in the first two paragraphs, and the Args list is compact. Slightly verbose in repeating the query parameter name before 'The search', but every line 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 9-param search tool with an output schema, the description covers purpose, the alternative, and every parameter's semantics. It stops short of documenting defaults (page=1, rows=10) or pagination termination behavior, which are minor residual 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 0%, so the description must compensate, and it does: every one of the 9 parameters is documented with meaning and often format (mediatype values, rows 1-100, sort examples, kind mapping). This is exactly what the low-coverage schema needs.

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) plus resource (Internet Archive item metadata) and enumerates the searchable fields (title, author, subject, description). It also carves out the boundary explicitly with 'Not the text inside books,' which cleanly separates it from ia_fulltext_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?

Names the alternative tool (ia_fulltext_search) and the exact condition that selects it ('find a phrase inside scanned books'). It further warns about the noisy 'maps' kind, giving the agent a real usage caveat rather than just a 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?

With no annotations, the description carries the load and does reasonably well: it explains the `configured: false` state, that a free API key clears it, and that Internet Archive and Wikimedia Commons need no key. It stops short of describing the full response shape, though the output schema covers 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?

Two tight sentences: the core purpose first, then the operational nuance about API keys. No filler, and the most important 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 no-parameter discovery tool with an output schema, the description is complete: it says what is returned (archives, readiness, suggested use) and covers the one gotcha (keyless vs keyed sources). Return shape is delegated correctly to the output 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?

The tool takes zero parameters, which is the baseline 4 case. Schema coverage is 100% and there is nothing to document, so no descriptive burden exists here.

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 (List) and resource (the archives this server can search) plus the payload contents (readiness and fitness). It is immediately distinguishable from the search/get siblings, which all operate on content rather than the source catalog itself.

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 a discovery/preflight role by explaining readiness and usefulness, but never explicitly says when to call it (e.g., before searching, or to determine which sources are available). No alternative is named or excluded, leaving usage 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?

With no annotations, the description carries the full burden, and it does add one genuinely useful operational fact: an API key is required. However, it says nothing about pagination behavior, ordering, or what happens when the parent has no children or an invalid ID, so behavioral disclosure is partial.

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; the purpose and scope lead, and the auth prerequisite follows. Nothing is redundant or padded.

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 described. Still, for an un-annotated tool with zero parameter documentation, the description omits pagination semantics and parent-ID format, leaving real gaps an agent would only discover by trial.

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 three parameters, so the description must compensate and largely does not. 'parent_na_id' is only obliquely implied by 'children of a series or file unit', and 'page'/'limit' are never mentioned at all — an agent gets no hint that results are paged.

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 ('List') and resource ('immediate children of a series or file unit') with precise scope ('one level down'), which is more than a restatement of the name. It does not explicitly differentiate itself from siblings like nara_get_record or nara_search, so it stops 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?

Usage is implied by the scope: call this to walk one level below a known parent. There is no explicit when-to-use/when-not guidance and no named alternative (e.g. nara_search for discovery vs. this for hierarchy traversal), leaving routing 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?

With no annotations, the description carries the full burden. It usefully discloses the auth requirement and the 4,000-character truncation of long strings, which is real behavioral context. However it says nothing about pagination behavior (despite page/limit params), what happens for records without digital objects or OCR, or rate 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 the core action and the truncation caveat second. No filler, though the truncation note could be tied to the limit parameter for tighter 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?

An output schema exists, so return-value explanation is not required. But for a 4-param tool with 0% schema coverage and no annotations, the description leaves pagination and object selection unexplained, which is a meaningful gap for correct invocation.

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 4 parameters. The description only hints at the record identity and says nothing about page, limit, or object_id — the pagination and object-selection semantics are entirely undocumented in both the schema and the 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 and resource: retrieve OCR text extracted from a record's digital objects. An agent can distinguish this from nara_get_record (metadata) by the 'extracted text' scope, but the description never explicitly names or contrasts the sibling 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?

It states the auth prerequisite (NARA_API_KEY) but gives no when-to-use guidance, no condition that selects this over nara_get_record or the other text tools, and no note on when OCR may be unavailable.

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 provided, so the description carries the full burden. It usefully discloses an auth requirement (NARA_API_KEY) and hints at payload contents (digital objects, ancestry), but says nothing about rate limits, error behavior if the naId is absent/invalid, or rate/scope of the read.

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, front-loaded with the core action and scope, then the prerequisite. No 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 values need not be explained, and the description still flags payload scope. For a single-parameter read tool the definition is nearly sufficient; only the missing usage routing and edge-case behavior keep it from being 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 only parameter is titled 'Na Id', so the description's phrase 'numeric naId' is what tells the agent this is a NARA catalog identifier and that it must be an integer. That adds real meaning but is minimal for a 1-param tool with no schema documentation.

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 (Catalog record) and pins the lookup key to the numeric naId, with extra scope ('with digital objects and ancestry'). This distinguishes it from the nara_search sibling, though it does not explicitly contrast with the generic get_record sibling.

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: the agent must already hold a numeric naId (presumably from nara_search). There is no statement of when to use this over nara_search or nara_children, and no exclusions or prerequisites beyond the key requirement.

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 behavioral burden and does well: it discloses the NARA_API_KEY requirement, the 10,000 queries/month default budget, the hard 'one page per call, at most 100 records' limit, and that the API terms forbid scraping or bulk download. It even flags uncertainty ('unverified until a key has been used against the live service') for the kind mapping. It stops short of describing error behavior or throttling consequences.

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 critical constraints (auth, rate limit, pagination cap, no scraping) are front-loaded before the Args block, and the per-parameter list is compact. Some parameter glosses are one-liners that could carry more, but there is little 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?

An output schema exists, so return values needn't be re-explained; the description instead covers auth, budget, pagination limits and legal constraints. For a 15-parameter tool it is complete enough to invoke correctly, though the lack of sibling routing is 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 0%, so the description must compensate, and it does: every one of the 15 parameters gets a plain-language gloss (query operators for q, date formats for start_date/end_date, examples for type_of_materials and record_group, ranges for limit/page). A few entries are thin ('Words in the title', 'Latest date'), so it is not exhaustive, but it far exceeds 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 and resource ('Search the US National Archives Catalog'), so the agent knows exactly what the tool does. It does not, however, explicitly distinguish itself from siblings like nara_children, nara_get_record, or the other search tools (ia_search, dpla_search), leaving that differentiation to inference.

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 through the auth requirement and the 'one page per call' constraint, and it names usage_report as where to find remaining budget. But it gives no explicit when-to-use/when-not guidance and no comparison against the sibling NARA tools or the other archive 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?

With no annotations, the description carries the full burden and does so well: it discloses the per-source date-filter asymmetry, the experimental fulltext endpoint, that `kind` is translated per archive (`kind_applied`) with maps being lossy/noisy, and that `rights.reuse` is a filtering aid rather than legal advice with `unknown` meaning no statement. These are exactly the behavioral traits an agent cannot infer from 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?

Well structured and front-loaded — summary, then the rights caveat, then a scannable Args block. It runs long, and the enumerated rights values partly restate return-shape territory covered by the output schema, but nearly every line carries actionable guidance.

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; the description covers all parameters, the cross-archive behavioral quirks, defaults, and the escape hatch to `list_sources`. An agent has everything needed to call this correctly on the first attempt.

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 and it documents all seven parameters with meaning beyond types: sources enumerated (internet_archive, commons, dpla, nara, smithsonian), limit range 1–25, date filtering semantics per archive, fulltext's experimental nature and result location, and `kind`'s vocabulary mapping.

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 opening sentence gives a specific verb and resource with scope: 'Search several archives at once and return normalised records grouped by source.' The 'several archives at once' framing implicitly but clearly separates it from the single-archive siblings (ia_search, commons_search, dpla_search, nara_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 states when the multi-source behavior applies and routes to the sibling `list_sources` for the set of ready sources, plus notes that date filters are only honored by some archives. It stops short of explicitly saying when to prefer a single-archive sibling instead (e.g. use ia_search for Internet Archive depth), so it lacks an explicit exclusion.

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 provided, so the description carries the full behavioral burden. It discloses the auth requirement (API key), which is genuine value, but says nothing about read-only nature, failure behavior for unknown ids, or rate limits – though an output schema exists to cover the 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?

Two short sentences, no waste, and the core action and identifier format are front-loaded ahead of the auth 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?

For a single-parameter getter with an output schema, the description covers the essentials: what it fetches, the id format, and the credential needed. Only marginal gaps remain around error/not-found 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?

With one parameter at 0% schema coverage, the description must compensate, and it does by supplying a concrete id example ('edanmdm-nmaahc_2012.36.4ab') that shows the expected format. It does not explain whether the id is a Smithsonian EDAN id versus some other key, so it is not fully compensating.

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 ('Get one Smithsonian record by id') and gives a concrete example identifier, which implicitly separates it from the search siblings like si_search. It stops short of naming an alternative explicitly, so it lands just below the top tier.

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 a prerequisite ('Needs SMITHSONIAN_API_KEY') but never states when to reach for this tool versus si_search or get_record. Usage is only implied by 'by id' – an agent with an identifier will infer it, but there is no explicit when/when-not 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?

With no annotations the description carries the full burden, and it does disclose two meaningful behaviors: the SMITHSONIAN_API_KEY auth requirement and the rights semantics (CC0 media returns rights.reuse "free", otherwise "Usage conditions apply"). It stops short of rate limits or pagination/error behavior, but the auth and rights disclosure is genuinely valuable.

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 the purpose and auth requirement before a structured Args list, and every line carries information. The Args block is a bit long but each entry earns its place by documenting an otherwise undocumented parameter.

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 format need not be explained, and the description covers auth, all parameter semantics, and rights semantics. It is largely complete for an 8-parameter search tool, with only pagination behavior and usage-versus-siblings guidance 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 0%, so the description must compensate, and it does for all 8 parameters: rows range (1-100), sort options with default, the EDAN record type, row_group values, category enums, and the object_type/online_media_type mapping for kind. This adds real meaning beyond the bare 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 and resource ('Search Smithsonian Open Access records'), which cleanly separates it from the sibling source searches (nara_search, ia_search, dpla_search, commons_search). An agent can route to it 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 the API-key prerequisite and points to si_terms for fielded query syntax, which is useful routing context. However, it never states when to use si_search versus si_get_content, si_terms, or the other source-specific search tools, so the when-not guidance is absent.

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 provided, the description carries the full burden. It usefully discloses the auth requirement and that counts cover only CC0-licensed content, but says nothing about whether the call is read-only (implied), rate limits, or whether counts are collection-wide or scoped. The output schema presumably covers the 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?

Two short sentences, front-loaded with the result the tool produces and followed by the auth prerequisite. 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?

An output schema exists, so return values need not be described, and the description covers the resource scope and the auth requirement. It could say more about whether the stats are global or filterable, but for a zero-parameter counter it 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?

The tool takes zero parameters, so the baseline is 4 — there are no argument semantics left for the description to explain. Schema coverage is reported at 100%.

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 resource (CC0 objects and media counts) with the implied verb 'counts', and the 'CC0' scoping makes it distinguishable from the search/fetch siblings. It does not explicitly name an alternative, but no sibling does anything similar, so confusion risk is low.

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 a prerequisite ('Needs SMITHSONIAN_API_KEY') but no explicit when-to-use or when-not-to-use guidance. Usage is implied by the purpose — call it to get aggregate collection counts — but there is no routing or exclusion language.

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 provided, so the description carries the full burden. It usefully discloses the auth requirement (SMITHSONIAN_API_KEY), but says nothing about pagination/limit behavior, rate limits, or result shape. The auth note is real added value, but the safety/operational profile is thin for a no-annotation 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?

Two tight sentences, front-loaded with the core action and then the enumerated vocabulary. The category list is long but earns its place as the key semantic payload; 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 an output schema present, return values need not be explained, and the auth requirement is covered. However, two of three parameters remain undefined and there is no guidance on result size or how to consume the vocabulary, leaving the definition only adequate for a 3-param 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 0%, so the description must compensate. It does document the accepted values for the required `category` parameter (culture, data_source, date, place, topic, unit_code, etc.), which is genuinely useful, but `limit` and `starts_with` are left entirely undocumented in both schema and description. Partial compensation only.

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 (list) and resource (the vocabulary for a search field), and enumerates the exact categories the field accepts. An agent can tell this is a lookup/controlled-vocabulary tool rather than a search tool like si_search, though it never names a sibling 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?

"Useful for building fielded queries" implies when to reach for it, but there is no explicit when-not guidance or named alternative (e.g. si_search for the actual query). Usage is inferable 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?

No annotations are supplied, so the description carries the full behavioral burden. It does disclose the temporal scope (this month, this session) and the per-source granularity, which is real added context, but it never states that the call is a side-effect-free read, whether it requires auth, or whether it is cheap to call repeatedly.

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; it leads with what the caller gets and moves straight to scope details. 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?

An output schema exists, so the description is not obliged to explain the return shape, and it correctly focuses on the data's scope instead. For a zero-parameter read tool this is nearly sufficient; only the auth/side-effect profile is left unstated.

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 are no inputs whose semantics need explaining, and the schema has no gaps to compensate for.

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 specific resource and scope: request counts for this month and this session, broken down per source, plus the last-seen provider rate limit. That is enough to distinguish it from the retrieval-oriented siblings (si_stats aside), though it omits an explicit verb like 'report' and never contrasts itself with si_stats.

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 statement or named alternative, but the mention of 'the provider rate limit last seen' strongly implies the motivating scenario: checking quota before or after sustained API use. Usage is inferred rather than stated.

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