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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add workflow context — which it does by disclosing the no-args default return and the fact that section listing requires an identifier obtained from a prior response. It doesn't discuss result size, pagination, or ordering, so it isn't exhaustive.

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, front-loaded with the hierarchy shape, then the default behavior, then the workflow hint. No filler and every sentence carries information an 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?

An output schema exists, so return-value explanation is unnecessary, and the description still covers default behavior and the call chain for each level. The only omissions are pagination/volume expectations for large listings, which matters mildly for a browse tool with four optional filters.

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 examples for each param, so the baseline is 3; the description adds genuine meaning on top by explaining the hierarchy ordering and that subject_group identifiers come from a previous response rather than being constructed by the agent. That prerequisite is not derivable from 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 — 'Navigate the Title 38 hierarchy (title → chapter → part → subpart → subject group) and list what exists at a level' — and enumerates the exact levels, so an agent knows precisely what the tool returns. It also implies the boundary versus search_regulations ('before searching') and get_section, which is enough to separate it from siblings.

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 says when to use it ('to discover valid parts/subparts before searching') and describes the no-argument default ('returns the chapters'). The chained-call guidance ('pass the subject_group identifier you saw in a previous response') tells the agent the prerequisite for deeper levels. It stops short of naming specific alternative tools by name, which keeps it at 4.

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 readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral facts: stateless operation, full-title XML fetched from eCFR and hashed per citation, no cache or local index, and a 100-entry cap per list surfaced via `truncated: true`. The error-before-fetch behavior for invalid dates is also disclosed. Only gap is no indication of latency/cost implications of fetching two full-title XML documents.

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 purpose and the changed/added/removed triad, then alternative routing, then behavior, then error cases — a sensible order. The parenthetical about the local CLI is long and dense, but it carries real routing value rather than 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, yet the description still flags the one return-value detail an agent must act on (`truncated: true` meaning a list was cut) plus the 100-entry cap. Combined with stated statelessness, fetch behavior, and error preconditions, nothing an agent needs to call 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% and already documents both params as YYYY-MM-DD, so the baseline is 3; the description adds real value by stressing both are required with no default-to and that identical or impossible dates are rejected pre-fetch. It does not elaborate on the directional semantics beyond the names `from_date`/`to_date`.

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 ('Provision-level diff of Title 38 between two eCFR issue dates') and enumerates the three output categories (changed, added, removed). It clearly separates itself from the local CLI `cfr-free diff`, but never mentions the sibling tool `redline`, so an agent must infer how this differs from that overlapping diff tool.

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 names the alternative workflow: 'for "what changed since my index was built" run `cfr-free diff <from>` locally, which resolves `to` from the index issue date.' It also states the precondition that both dates are required and that there is no default-to, plus the rejection conditions (identical dates, impossible calendar dates).

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, openWorld=false, so the safety profile is covered; the description adds the output medium (markdown) and names the returned fields (heading, hierarchy path, issue date, permalink). It doesn't say what happens on an ambiguous or unmatched citation, which is the main remaining behavioral unknown for a lookup 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?

Three short sentences, each doing distinct work: what it returns, what input it accepts, what comes back. No repetition of the name or title and 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?

For a single-parameter read with full schema coverage, complete annotations, and a declared output schema, the description covers purpose, accepted input forms, and output medium. Nothing an agent needs in order to call it 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%, so baseline is 3, and the description earns above that by enumerating genuinely different citation syntaxes (bare section, §-prefixed, fully qualified, appendix names) that the schema only gestures at with one example. It stops short of stating whether leading/trailing whitespace or part qualifiers are tolerated.

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?

Starts with a specific verb+resource pair ("Fetch the full text of one Title 38 CFR section or appendix") plus the output format (markdown), which is far more informative than the title. It doesn't disambiguate from the similarly named sibling get_section_at, so an agent comparing the two must infer the difference from the sibling's schema rather than this 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?

Usage context is implied by "one ... section or appendix" (i.e., a single known citation, not a search), but there is no explicit when-to-use vs. search_regulations, browse_title38, or get_section_at. The accepted-format list helps the agent shape input more than it helps choose this tool over its siblings.

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

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

Beyond the read-only/idempotent annotations, the description discloses key behavior: eCFR serves the revision in force on the date, the response names the requested date rather than the served revision, and calls are stateless with no cache. It also states that dates before 2017-01-01 are rejected as not_found.

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 front-loaded with purpose, followed by date-resolution behavior, statelessness, archive boundary, and usage routing. It is dense but every sentence contributes, and there is 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?

Given two required params, full schema coverage, an output schema, and read-only annotations, the description supplies everything an agent needs: date semantics, rejection boundary, statelessness, and sibling differentiation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real semantic value about at_date: it resolves to the revision in force, the upstream does not report the served issue date, and pre-2017 dates are rejected. Citation semantics are largely 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?

The description opens with a specific verb and resource: reading one Title 38 provision as it stood at a requested date. It explicitly distinguishes itself from the sibling get_section by naming that alternative for current 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?

It gives explicit use cases for date-of-claim and CUE questions, and explicitly routes current-text requests to get_section. The before-2017 exclusion is also stated as a rejection condition.

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, so the safety profile is covered. The description adds real value beyond that: the semantics of each state, the remediation for 'empty' (run `cfr-free sync`), and the obligation to verify 'stale'/'degraded' results against the current eCFR. It does not mention latency or whether the check is cheap, so a 4 rather than 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?

Single front-loaded sentence that leads with the verdict concept, then defines each state inline. Dense with nested parentheses and em-dashes, which makes it slightly harder to scan, but no sentence 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 the description need not explain return values, yet it still defines the four verdicts and their follow-up actions — more than enough for a zero-param read tool. The one gap is failing to clarify the boundary with the sibling 'index_status'.

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 there is nothing for the description to disambiguate; the baseline of 4 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+resource ('one-call readiness verdict for the local index') and enumerates all four possible verdicts with their meanings, so an agent knows exactly what comes back. It does not, however, distinguish itself from the sibling 'index_status', which sounds like an overlapping concept — that ambiguity 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?

'Clients should gate queries on this before spending tool calls' gives an explicit when-to-use rule and even a cost rationale. It stops short of naming an alternative or a when-not-to-use case (e.g., after a sync is known to be fresh), and never mentions the similar-sounding 'index_status' sibling.

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, so the safety profile is carried. The description adds value annotations cannot: the receipt hash is a sha256 over sorted (citation, text+heading) pairs computed at rebuild time and is null on older indexes, and staleness is judged against the CFR_MAX_AGE_DAYS threshold. That is genuine behavioral context about data provenance and edge cases.

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: the first front-loads the verb and resource then enumerates the report contents, the second gives the actionable rule. The parenthetical about the receipt hash is long but every clause carries information an agent cannot get from the schema.

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 annotations plus the description together cover safety, provenance, and staleness. The one gap is what an agent should do with a stale verdict beyond 'check this before relying' — no remediation or fallback path is described.

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, so there is no parameter semantics to explain and the baseline is 4. Nothing in the description misleadingly implies inputs that do not exist.

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 ('Report') plus specific resource ('the local Title 38 index') with the exact fields returned enumerated: eCFR issue date, sync time, row counts, receipt hash, staleness. That is far beyond tautology. It does not, however, draw any line against the sibling 'health' tool, which is the most likely confusion for an agent deciding between status-style 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?

'Check this before relying on search results' gives a clear triggering condition tied to search_regulations. It stops short of naming alternatives or saying what to do when the report comes back stale, so it is clear context rather than a full when/when-not/alternatives rule set.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is fully covered. The description adds that results come specifically from the 'local index' and what fields are returned, but the return fields are already in the output schema, so the incremental behavioral disclosure is modest.

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 first states scope and return content, the second states the use case. Front-loaded and free of 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 a rich output schema and complete annotations, the description covers purpose, scope, and use case, leaving little for an agent to guess. Only minor details (ordering, whether the index can be stale/incomplete) are 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?

There are zero parameters, so the baseline is 4; nothing about parameter meaning needs documenting and the schema fully covers the (empty) input.

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 ('Enumerate') and resource ('Title 38 CFR part') scoped to the local index, and states the returned fields (structure-tree title, section/appendix counts). It is clear on its own, but it never names or contrasts with siblings like browse_title38 or search_regulations, which could plausibly overlap.

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 this to discover which parts are searchable' gives a concrete when-to-use condition tied to a downstream action. It stops short of stating when-not-to-use or pointing to an alternative sibling for related tasks, so it is clear context without 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?

Goes well beyond the readOnly/idempotent annotations: discloses that dates are selectors rather than verified issue stamps, that full-title XML is refetched per call with no cache, and the exact error ordering (date validation before fetch, not_found after fetch). Also explains the coarse-block degradation when the core line cap is exceeded.

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 and organized around output, error behavior, and statelessness, with no filler sentences. It is dense to the point of being a single long paragraph, which slightly hurts scanability.

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 stateless remote-fetch diff tool, it covers return shape, failure modes, cost implications (full-title fetch per call), and degraded-mode output, and an output schema already documents the payload. Nothing an agent needs in order to call it 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%, so the baseline is 3, but the description adds real meaning the schema cannot: the dates act as selectors for the revision in force, not as a guarantee of which issue date was served. The citation parameter itself gets no added semantics beyond the schema example.

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: a line-level redline of one Title 38 provision between two eCFR issue dates, enumerating the outcomes (changed/added/removed/unchanged). It is clearly narrower than whole-title siblings like diff_issues or single-date get_section_at.

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?

Clear usage context: both dates are required and there is no default-to, so the agent knows it must supply a comparison window. However, it never names diff_issues or get_section_at as alternatives, so routing between the comparison tools is left implicit.

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?

Adds substantial behavior beyond the read-only annotations: candidate-set semantics, three-tier ranking order, bm25 interpretation, citation pinning with `direct` and `inResults`, quoted-phrase/prefix behavior, and explicit caveats that ranking is lexical not authoritative. These details materially affect how an agent should interpret and cite 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 the purpose and core search semantics, and nearly every sentence carries operational meaning. It is dense and long, but the length is largely justified by the complexity of ranking, pinning, and matchedTerms behavior.

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 six parameters, full schema descriptions, an output schema, and read-only annotations, the description covers what an agent needs: result ordering, candidate-set scope, citation pinning, matched/unmatched terms, and citation-safety guidance.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds useful semantics: example part numbers ('4' for ratings, '17' for prosthetics), clarification that chapter is exact and case-sensitive, and the effect of `page` on pinned citation totals.

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: full-text search across the local Title 38 CFR index. It clearly distinguishes itself from siblings by telling the agent to follow up with get_section to read a hit in full.

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 concrete scoping guidance for `part`, `kind`, and `chapter`, and explains that citation queries are pinned. It does not explicitly say when to use browse_title38 or get_section_at instead, but the follow-up workflow with get_section is clear.

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