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

The description goes well beyond the minimal annotations by disclosing important behavior: delivery is HMAC-SHA256 signed, notifications fire only when the existing refresh finds real changes, nothing is crawled, and there is no real-time trigger. It also exposes the immutability constraint on channel and directs the agent to delete and recreate to change it. This is rich, behavioral context that annotations alone do not provide.

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, each earning its place: purpose, delivery/trigger behavior, and the immutability caveat. Important constraints are front-loaded and no redundant wording or restatement of the tool name appears.

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

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

Given the complexity of 8 parameters and no output schema, the description supplies the most decision-critical context: notification timing, delivery methods, and the channel immutability rule. It does not describe what a successful create returns, such as a watch ID, which would be helpful, but the rich per-parameter schema descriptions compensate for most remaining 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 coverage is high at 88%, so the schema carries most parameter meaning. The description adds genuinely new parameter-level semantics by stating that channel is immutable once set and that changing it requires delete and recreate, which is not in the schema. This goes beyond the baseline expected from a high-coverage schema, though most other parameter details 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?

The description opens with a specific verb and resource: 'Subscribe to a board so a change to that source notifies you.' It clearly defines the tool as watch creation and distinguishes it from siblings like update_watch, delete_watch, and list_watches by focusing on the notification-subscription action. It also adds key delivery specifics (webhook/email) that make the tool's role concrete.

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 strong context for when to use it: when a board needs to be watched and notifications are desired, with explicit clarification that delivery only happens on real changes found during existing refreshes. However, it does not explicitly name alternatives or state when not to use it, such as 'to modify an existing watch, use update_watch instead.' Usage is implied rather than directly contrasted with sibling 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?

Beyond the annotations (destructiveHint: true), the description discloses the nature of the destruction: deletion is 'immediate and permanent' and 'its delivery history goes with it.' This cascading data-loss warning is precisely the behavioral context annotations cannot convey.

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, zero waste: core action, irreversible consequence, and alternative routing. The most critical fact (permanence/history loss) is front-loaded in the second sentence, and 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?

Complete for a single-parameter destructive tool: it covers the action, scope, consequences, and the safer alternative, and annotations carry the destructiveness profile. The only gap is unstated failure behavior (e.g., nonexistent or unowned watch_id), which is minor given the strong ownership constraint already expressed.

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

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

With 0% schema description coverage, the description must compensate, and it adds a meaningful constraint — the watch must be one the caller owns. However, it never explicitly mentions watch_id or explains where to obtain it, leaving that inference to the agent; it partially compensates but does not fully document the parameter.

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

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

The description states a precise verb-resource pair — 'Delete a watch you own' — and immediately differentiates from update_watch, which merely deactivates. The ownership scope and permanence make this unmistakably distinct from create_watch, test_watch, and list_watches.

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 (update_watch with isActive false) and states the exact condition for choosing it over deletion: when the user wants to stop notifications without losing the config or history. This is textbook when-to-use/when-not-to-use 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 readOnlyHint=true already covering non-mutation, the description adds meaningful behavior: it discloses the billing implication ('charged as a section lookup plus a body read') and the acceptance of citation URLs, bare paths, or Bluebook citations. This goes beyond the annotations without contradicting them.

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, each earning its place: primary function with return shape, alternative accepted inputs, and usage/billing context. The most essential action is front-loaded, and there is no redundant 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?

The tool has a single parameter, an output schema, and a readOnly annotation. The description covers the input sources, return type, preferred alternative, and billing impact, leaving no significant operational gap for an agent selecting or invoking the tool.

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

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

The schema provides no description for the single 'id' parameter (0% coverage), so the description compensates by explaining that the id comes from a search result and may also be a citation URL, bare path, or Bluebook citation. This gives an agent usable meaning for the parameter.

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 identifies a precise verb and resource: 'Fetch the full text of one US law section by the id from a search result.' It also specifies the return shape and lists alternative accepted inputs, making the tool's purpose unmistakable and distinct from siblings like get_us_statute_section_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?

The description gives clear usage context: it is intended for clients requiring the standard search/fetch pair, and it explicitly prefers get_us_statute_section_text when available. It does not enumerate exclusion conditions for other sibling tools, but it names the main alternative and the rationale for using this tool.

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?

The annotation already declares readOnlyHint=true, and the description adds useful behavioral context beyond that: the endpoint is free and requires no authentication. This helps an agent know there are no side effects or auth prerequisites, which is valuable for a simple 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?

The description is three short sentences that front-load the core resource and immediately state the most actionable facts: pricing, conversion rate, free usage, no auth, and when to use it. Every sentence earns its place with no redundancy.

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

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

For a zero-parameter, read-only pricing lookup with an output schema available, the description covers everything an agent needs: what the tool returns, cost-free invocation, no auth barrier, and intended use. No important contextual gap remains.

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 description does not need to document parameter meaning. The baseline of 4 applies, and the description does not introduce any conflicting parameter-related information.

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

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

The description clearly identifies the resource as current API credit pricing, including per-endpoint costs and the credit-to-currency conversion rate. It is immediately distinguishable from all sibling tools, which focus on statutes, watches, search, and sections.

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 explicit usage context: 'Use to check what a call will cost before making it.' It also notes the tool is free and requires no authentication. It does not explicitly name alternatives or exclusions, but none are needed for this unique pricing endpoint.

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?

The readOnlyHint annotation already signals safety, and the description adds valuable behavioral context beyond that: empty results mean no recorded change, not absence of publisher amendments. It also clarifies the data source ('our capture history, not the publisher's'), which is an important interpretative caveat an agent needs to avoid drawing wrong conclusions.

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, no filler. The core behavior and ordering are in the first sentence, and the critical caveat plus alternative are in the second. Every sentence earns its place and 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?

Given the output schema exists and all 6 parameters are documented with high coverage, the description needs only to clarify higher-level intent and data interpretation. It does exactly that, including the empty-list caveat and the distinction from publisher history. An agent has everything necessary to call this tool 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 100%, so every parameter is already well-documented in the schema. The description does not add parameter-specific meaning, but the baseline of 3 is appropriate because the schema carries the full semantic load and the description does not need to compensate.

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

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

The description states exactly what the tool returns: observed changes to one section over time, with kinds (added, amended, removed) and ordering (newest first). It clearly distinguishes this from the publisher's history by explicitly pointing to amendmentHistory, which prevents confusion with sibling tools related to watch changes or publisher metadata.

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 an explicit alternative: 'For the publisher's own history, read amendmentHistory on the section.' It also clarifies when this tool is appropriate — for our refreshes' capture history — and warns against misinterpreting empty results as proof that the section was never amended. This is strong routing 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?

The readOnlyHint annotation already covers the safety profile, and the description adds meaningful context about the inverse relationship to crossReferences. However, it does not disclose operational details such as pagination behavior, empty-result handling, or whether both USC and CFR results are always returned together; the schema covers limit, but the description itself adds no behavioral caveats.

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

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

The description is two sentences with the core result front-loaded and the intended use cases following immediately. Every clause earns its place, and there is no redundant restating of the tool name or title.

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

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

Given the rich schema, the readOnlyHint annotation, and the existence of an output schema, the description is nearly complete. It explains the inverse relationship and offers clear use cases. A small gap is the lack of any mention of the limit parameter or general response shape, but those are already covered by structured fields.

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

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

Schema description coverage is 100%, so the baseline applies. The description text itself adds no parameter-level meaning, but the act_id schema entry provides valuable guidance about not hand-building IDs and explains why doing so usually causes 404s. This is sufficient given the high schema coverage.

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 precisely defines the tool as returning USC and CFR sections whose text cross-references a given section, explicitly framing it as the inverse of the crossReferences field on a section lookup. This clearly distinguishes it from related section tools such as get_section_neighbors or get_section_definitions without ambiguity.

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

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

It provides concrete use cases: finding where a definition or requirement is actually invoked, or gauging how load-bearing a provision is across the code. It does not explicitly state when not to use the tool or name alternatives, but the context is clear enough for an agent to select it appropriately.

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 indicate readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond annotations: results are ranked by similarity, limited to state statutes, and describe cross-state subject matching. This helps an agent understand what to expect from the response.

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 purposeful sentences: the first defines the core function and ranking behavior, the second gives real-world use cases. No filler or redundancy, 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 read-only tool with a clear output schema, 100% parameter schema coverage, and an explicit statement of scope and ranking behavior, the description is complete. Agents have enough context to select and invoke the tool 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 100%, and both 'act_id' and 'limit' are described with examples and format details. The tool description does not need to repeat parameter semantics since the schema fully carries that burden. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: returns provisions in OTHER states addressing the same subject as a given state statute section, ranked by similarity. It explicitly scopes to state statutes and distinguishes itself from sibling tools like get_section_neighbors or get_section_cited_by by emphasizing cross-state comparison.

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

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

The description provides explicit use cases: fifty-state surveys, multi-jurisdiction compliance, and checking whether a home-state rule is typical or an outlier. It does not explicitly name alternatives or state when not to use the tool, but the use-case guidance clearly signals appropriate invocation contexts.

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 provide readOnlyHint=true, and the description aligns with that. The description adds behavioral context by explaining that definitions are parsed from the chapter's definitions section, which is useful for interpretation. It does not cover edge cases like missing definitions, but that is not critical for this simple read-only 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 description is compact: one sentence states the purpose and source, a second provides usage guidance with examples. Every sentence earns its place, with no redundant phrasing or fluff.

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

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

For a tool with one documented parameter and an output schema, the description fully covers what the tool does, how the output is derived, and when to invoke it. An agent has enough context to select and call it correctly without additional information.

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

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

The schema description covers 100% of the single parameter act_id, including format, example, and a warning about hand-building IDs. The tool description itself adds no parameter-level detail, but the schema already does the heavy lifting, so a baseline of 3 is appropriate.

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

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

The description states exactly what the tool returns: term definitions that govern a section, parsed from its chapter's definitions section. It distinguishes itself from sibling tools like get_section_changes or get_section_text by focusing on definitions of terms of art, making the purpose unmistakable.

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

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

The description explicitly says when to use the tool: whenever a provision depends on a term of art and the statute's own definition is needed rather than the ordinary meaning. This clear condition, with examples like 'covered entity' and 'security', effectively routes the agent to the correct tool.

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?

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful context about statutory ordering and chapter scope, but does not disclose further behavioral details such as behavior when no neighbors exist or whether the result includes the given section itself. No contradiction with annotations exists.

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

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

The description is two focused sentences. The core behavior is front-loaded, and the second sentence gives concrete use cases without fluff. 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?

Given the read-only annotation, full schema coverage, an output schema, and clear use-case guidance, the description is complete enough for an agent to select and invoke the tool correctly. The act_id assembly warning closes the main correctness 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by warning agents not to hand-assemble act_id: 'the title and section are derivable from a citation but the CHAPTER is not, so hand-built ids usually 404.' This is valuable practical guidance that prevents invocation errors.

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

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

The description clearly states the verb (get) and resource (sections immediately before and after a given section), and specifies the ordering and scope: 'within its own chapter or code, in statutory order.' This distinguishes it from sibling tools like get_section_changes or get_section_cited_by without needing to inspect schemas.

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

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

The description explicitly identifies when to use this tool: 'to read a provision in context, to find a definitions or penalties sibling, or to check whether the operative language continues into the next section.' It does not explicitly mention when not to use it or name alternatives, but the use cases are concrete and actionable.

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 readOnlyHint annotation, the description discloses that missing sections are silently skipped and are not charged, which materially affects how an agent should interpret partial results. The schema description also reveals duplicate collapsing and order preservation, adding important behavior not present in annotations.

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

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

Three short sentences carry the core purpose, a cross-reference to the single-section sibling, and the key usage rule, with no filler. The most decision-relevant facts are front-loaded in the first sentence.

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?

Together with the detailed schema and an existing output schema, the description covers what data is returned, when to choose it, how to identify sections, and what happens when IDs are missing. No significant gap remains for an agent 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?

The input schema already covers actIds with examples, min/max counts, duplicate/order behavior, and a warning against constructing IDs from citations, so the tool description itself adds little parameter meaning. This matches the baseline of 3 for high schema-description coverage.

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 names a concrete operation (get metadata for up to 50 sections) and the required resource identifier (act_ids), making the tool's scope immediately clear. It also distinguishes itself from get_us_statute_section by positioning itself as the batch equivalent.

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

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

It explicitly says to use this instead of looping get_us_statute_section when several act_ids are already available, and gives a concrete example. The parameter schema further adds an exclusion: do not synthesize IDs from citations, and names resolve_statute_citation as the alternative.

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?

The readOnlyHint annotation already indicates a safe read operation, and the description adds value by disclosing what is NOT included (section text) and what is included (HTML/PDF/XML links, history). The 'before paying for its full body' note gives useful operational context about cost/effort. No contradiction with annotations.

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

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

Three tight sentences: first states the core output, second clarifies the key exclusion and redirects to the right tool, third summarizes the ideal use case. No filler, front-loaded, and 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?

Given the single required parameter, the readOnlyHint annotation, and the presence of an output schema, the description fully covers what the tool does, what it does not do, when to use it, and which sibling to use instead. There is no obvious missing context needed for an agent 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 coverage is 100% and the schema already explains act_id with an example and formatting guidance. The tool description itself does not add parameter-level details, but it does not need to because the schema is thorough. The baseline of 3 is appropriate since the schema carries the heavy lifting.

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

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

The description states that the tool returns metadata for a single statute/regulation/rule section keyed by act_id, specifying concrete contents like citation, hierarchy, breadcrumb, and amendment history. It explicitly excludes full section text and names a sibling tool that provides it, so it is sharply differentiated from get_us_statute_section_text and other siblings without needing to open schemas.

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

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

The description gives clear when-to-use guidance: use it to confirm the correct section before retrieving the full body, and explicitly says to use get_us_statute_section_text when section text is needed. This is direct, actionable routing among alternatives.

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 declare readOnlyHint=true, so safety is already covered. The description adds behavioral detail about return representations—styled HTML with cross-references and paragraph numbering, plus plain text—which goes beyond the annotation. It does not contradict annotations.

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

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

The description is two sentences with no filler. It front-loads the core function, then adds output details and a clear usage directive. 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?

Given the rich parameter schema, readOnly annotation, and presence of an output schema, the description is complete enough for an agent to select and invoke the tool correctly. Complex behaviors like asOf reconstruction are documented in the schema, so the main description does not need to repeat them.

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

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

Schema description coverage is 100%, so the schema already thoroughly documents all parameters including asOf, format, and structured. The description only mentions act_id and adds no extra parameter-level meaning beyond what the schema provides, warranting the baseline score.

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

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

The description clearly states the tool retrieves the full text of a US statute, regulation, or rule section by act_id, and specifies the output formats: styled HTML and plain text. It also differentiates the tool from citation-only or metadata-focused siblings by emphasizing actual statutory language for quoting, drafting, or analysis.

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 an explicit use case: 'Use when you need the actual statutory language to quote, draft against, or analyze rather than just cite.' This provides clear context for when to choose this tool, though it does not enumerate exclusions or name alternative sibling 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?

Beyond the readOnlyHint annotation, it discloses important behavior: a missing side is not an error, hasBefore/hasAfter indicate presence, and null should be rendered as 'diff unavailable' rather than treated as failure. It also surfaces cost and output-format differences from siblings. No contradiction with annotations.

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

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

Three dense sentences with no filler. Core behavior is front-loaded, followed by edge-case semantics and a practical cost warning. Every clause 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?

Given no output schema, the description adequately conveys the return shape (before/after documents, hasBefore/hasAfter flags), the hasDiff precondition, and the null-handling behavior. It could be slightly more explicit about the exact response fields and the meaning of watch_id, but it is largely complete for a capable agent.

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 schema has 0% parameter description coverage, and the description does not explicitly define watch_id or change_id. However, 'one specific change' and 'change list' provide meaningful context for change_id, and the parameter names are self-descriptive enough to partially compensate.

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

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

The description clearly states the tool returns full section text before and after one specific change, ready to diff. It also distinguishes itself from sibling law-change tools by noting it returns section text and only applies where hasDiff is true.

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 guidance on when the tool is meaningful (hasDiff true), how to handle missing sides, and a cost warning before looping. However, it does not name specific alternative tools, only implies them with 'Unlike the rest of the law-change 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?

The readOnlyHint annotation already establishes this is a safe read operation. The description adds useful behavioral context beyond that: boards are tracked corpus sources, the result includes refresh cadence, and board identity depends on corpusType plus state with state null for federal. This is meaningful semantic context without contradicting the annotations.

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

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

Two sentences cover the core action, the domain model, and the intended use case with no filler. 'List every watchable board' is front-loaded, and every clause 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?

Given the rich parameter schema and readOnly annotation, the description is largely complete for a listing/discovery tool. There is no output schema, so a tiny bit more detail about the returned board shape could help, but the mention of refresh cadence and the connection to create_watch give sufficient context for an agent to call 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 100%, so the schema already documents every parameter, including state's special 'federal' meaning and corpusType case-insensitivity. The description adds no parameter-level details beyond what the schema provides, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'List every watchable board,' then defines what a board is with concrete examples. It also clarifies the identity model (corpusType plus state) and ties the tool to subscription discovery, which separates it from sibling tools like list_watches.

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

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

The description explicitly says to use it 'to discover what can be subscribed to before calling create_watch,' giving a clear when-to-use context. It does not explicitly name alternatives or state when not to use it, but the discovery-before-subscription framing provides enough routing 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?

The readOnlyHint annotation already covers the safety profile. The description adds useful behavioral context beyond that: it operates at any hierarchy level, returns children in statutory order, and is iterative ('walk'). This is meaningful added transparency.

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

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

Two sentences with no filler. The first sentence states the core operation and ordering; the second gives the use cases. Every phrase earns its place 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?

Given the readOnlyHint annotation, the exhaustive schema with 100% coverage, an output schema, and a clear description, nothing an agent needs to call this correctly is missing. The hierarchy-walking behavior and use cases are fully conveyed.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description does not add parameter-level meaning, but the schema itself fully documents each parameter with examples and corpus-specific notes, so no compensation is needed.

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

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

The description states a precise action ('list the child divisions') and a specific resource (the statutory hierarchy: titles, chapters, parts, or sections). It also distinguishes itself from search-like tools by explicitly framing the purpose as structural browsing rather than known-section lookup.

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 clear context: use this to browse a code when you do not yet know the section number, or to enumerate everything under a chapter. It does not explicitly name alternatives or state when not to use it, but the implied usage boundary is strong.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context about the tool representing a coverage matrix rather than performing any mutation. However, it does not describe response shape beyond 'section counts,' which is minor since the tool is read-only and parameterless.

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

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

Two sentences, front-loaded with the core purpose and then the usage context. Every sentence earns its place with no redundant wording.

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 zero parameters, a read-only annotation, and no output schema, the description sufficiently explains what the tool returns and when to invoke it. The coverage matrix and per-jurisdiction counts are enough for an agent to understand the response conceptually.

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

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

The tool has zero parameters and the schema has 100% coverage with an empty properties object, so there are no parameter semantics to explain. The description reinforces that the tool needs no inputs to return the full coverage matrix.

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

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

The description clearly states the tool lists a coverage matrix with every corpusType and per-jurisdiction section counts. This is a specific verb-resource pairing and distinguishes it from sibling list tools like list_statute_divisions or list_boards.

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

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

It explicitly says to use this tool before answering a jurisdiction question to verify coverage, and to avoid searching a nonexistent corpus. This gives the agent clear contextual guidance and an implicit alternative action.

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?

The description adds meaningful behavioral detail beyond the readOnlyHint annotation: it writes nothing, cannot suppress or double-fire a delivery, returns metadata only, never section text, and covers the entire captured history. This gives an agent a solid understanding of side effects and scope.

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

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

The description is compact and front-loaded with the core purpose, then adds scope, safety, and paging guidance in a logical order. Every sentence earns its place and there is no redundant or filler content.

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

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

Given the tool's complexity with seven parameters and no output schema, the description covers key needed context: what is returned, the metadata-only guarantee, history scope, safety, and cursor-based pagination. It does not detail every parameter, but the rich schema descriptions fill that 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 high at 86%, so the schema already documents parameters thoroughly. The description reinforces the paging pattern with sinceId and the returned cursor, but does not add much semantic meaning beyond what the schema provides. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool lists what a watched source added, amended, or removed, with specific fields and ordering. It also distinguishes itself from related watch/section tools by emphasizing metadata only and never section 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?

The description gives strong usage context: it is safe to poll, covers the board's whole history rather than just since subscription, and explains paging with sinceId and the returned cursor. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to select this tool appropriately.

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 readOnlyHint annotation, the description discloses retention (90 days), webhook-only logging, and the empty-list behavior for email-only watches. This materially shapes agent expectations about empty results despite the read-only safety signal.

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 carry purpose, scope, constraints, and usage intent with no filler, and the most important scoping claim is front-loaded.

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

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

With no output schema, the description covers the essential return content (status code, error, attempt number), retention, and the empty case. It does not specify ordering or any additional response fields, so it is strong but not exhaustive.

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 schema already documents limit, and the description adds only implicit meaning for watch_id via 'for one watch.' It does not elaborate on limit or provide richer guidance for either parameter, so with 50% schema coverage the description does only partial compensation.

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 it is a per-attempt delivery log for one watch and enumerates its content (status code, error, attempt number), so an agent can distinguish it from list_watches and list_watch_changes. The webhook-only qualification further narrows the resource and behavior.

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 gives the intended use: 'debug a webhook that is not arriving,' and tells agents not to expect results for email-only watches. It does not name a specific alternative sibling, so it falls just short of full routing 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?

The readOnlyHint annotation already signals a safe read operation. The description adds meaningful context by enumerating what is returned (board, channel, destination, active state, last delivery outcome) and the ownership scope ('you own'). This exceeds what the annotation alone provides.

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, purposeful sentences. The first explains the resource and returned fields; the second gives the practical purpose. No filler, no repetition of schema details, 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 simple read-only list tool with no output schema, the description covers what the agent needs: the resource, scope, returned fields, and how to use the output. Pagination parameters are documented in the schema, and the annotation covers safety. Nothing essential 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 description coverage is 100%, with both limit and offset fully documented in the input schema. The description does not add parameter-specific guidance, but it does not need to because the schema already explains the pagination semantics clearly. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') with a clear resource ('board watches you own') and enumerates the exact fields returned. It also states the primary purpose of the result ('find a watchId'), which distinguishes it from sibling watch-related tools like list_watch_changes and list_watch_deliveries.

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

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

The description explicitly tells the agent when to use this tool: to find a watchId for the other watch tools. It does not provide explicit negative guidance about when not to use it, but the stated use case is clear enough to avoid obvious confusion with sibling 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?

The readOnlyHint annotation already establishes that the tool does not mutate anything. The description adds useful behavioral detail by stating the output includes a confirmed exact section, official source link, and act_id. It does not disclose failure behavior like unresolved citations, but the parameter schema and output schema help fill that gap.

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 just two sentences, with the core action and output front-loaded and the usage guidance in a compact second sentence. Every part earns its place, and there is no filler or redundant restating of the title.

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

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

Given the full parameter schema coverage, the readOnlyHint annotation, and the existence of an output schema, the description is sufficiently complete for an agent to select and invoke the tool correctly. Critical semantics like jurisdiction constraints are already covered in the 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?

Schema description coverage is 100%, and each parameter already has rich examples and explanations, including the 'constraint, not a hint' nuance for state and corpusType. The description itself adds little parametric meaning beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description states a clear action ('resolve') and a specific resource (Bluebook citation strings), and specifies the outcome: exact section, confirmed, with an official source link and act_id. It distinguishes from search-style tools by saying it is for citations rather than questions, but it does not distinguish itself from the closely named sibling resolve_statute_citations_batch.

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

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

The description explicitly says to use this tool whenever the user provides a citation rather than a question, and explains it is more reliable than searching for citation text. This gives clear usage context, though it does not mention exclusions or the batch sibling as an alternative.

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?

The readOnlyHint annotation already establishes non-mutating behavior, so the description does not need to restate that. It adds useful context beyond the annotation: the call returns the same confirmed section, official source link, and act_id as the single-citation tool, and it is cheaper in credits and latency. Schema notes about duplicate collapsing further enrich behavior.

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 with no filler. The first sentence states capability and return parity; the second gives the use case and cost rationale. All information is front-loaded and relevant.

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 does not need to enumerate return fields. It covers the essential operational context: batch size, equivalence to the single tool, and the efficiency trade-off. An agent has enough information to select and invoke the tool 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 100%, so the input schema already explains each parameter, including examples and the meaning of state, citations, and corpusType. The tool description adds no new parameter-level detail, but that is acceptable given the high schema coverage.

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: 'Resolve up to 50 Bluebook citations in one call.' It also explicitly names the single-citation sibling and clarifies the batch variant's scope, so an agent can immediately distinguish it from resolve_statute_citation.

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 states exactly when to use the tool: 'Use when a document or answer cites several provisions.' It also explains the benefit over the alternative and names that alternative ('looping the single-citation tool'), giving clear selection 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?

Annotations already provide readOnlyHint=true, so safety is covered. The description adds context beyond the annotation: this tool exists for compatibility with clients requiring the standard search/fetch pair, and it lacks filtering capabilities. This is meaningful behavioral context without contradicting the annotation.

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 with no filler. The description front-loads the core function, then provides compatibility context, a routing preference, and a pairing instruction. Every sentence contributes actionable information.

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

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

Given the tool's simplicity, the existing readOnlyHint annotation, and the presence of an output schema, the description is complete. It covers what the tool searches, what it returns, when to use the alternative, and how to consume results with `fetch`.

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 single parameter `query` has 0% schema description coverage, and the description does not explicitly define query syntax or expected formatting. However, the description's statement of 'generic corpus search over US primary law' makes the query's purpose clear enough for a single simple string parameter, though it does not fully compensate for the absent schema 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?

The description states a specific verb ('search'), an explicit resource ('US primary law'), and the output shape (`{id, title, url}`). It explicitly distinguishes itself from `search_us_statutes`, so an agent can tell them apart without inspecting either schema.

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

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

It explicitly tells the agent when to prefer `search_us_statutes` over this tool and why, and instructs pairing with `fetch` to read results. This is clear routing guidance with conditions and an alternative 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 readOnlyHint=true already covering the safety profile, the description adds genuinely useful behavioral context beyond the annotation: the corpus scope searched, the hybrid semantic+keyword behavior, the return shape (citation, hierarchy, official source links), and the downstream consequence that hand-built act_ids 'usually 404.' No contradiction with the annotation.

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?

Four sentences that front-load scope, then usage, then returns and downstream workflow — every sentence earns its place for a tool with 23 parameters. The one redundant element is 'Filter by corpusType and titleNumber,' which the schema already covers, and the structure is otherwise tight and highly scannable.

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 an output schema exists and 100% param coverage, the description need not explain return values or parameter details. It covers scope, invocation trigger, key filters, return shape, and the act_id handoff to sibling tools — the essential selection and invocation context. The only gap is not routing the agent away from this tool when a citation is already in hand (resolve_statute_citation), and not disambiguating from the generic 'search' sibling.

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

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

Schema description coverage is 100%, so the baseline is 3 even with no param info in the description. The description only echoes 'Filter by corpusType and titleNumber,' which is already thoroughly documented in the schema. It adds no new meaning about parameter formats, defaults, or edge cases; the schema carries the entire burden as expected.

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 a specific verb (search), a precise resource (US primary law: USC, CFR, and all 50 states' statutes, regulations, constitutions and court rules), and the hybrid semantic+keyword mechanism. The closing sentence positions it relative to its siblings — the returned act_id 'feeds every other statute tool' — so an agent can tell this is the statute-search entry point, distinct from resolve_statute_citation, get_us_statute_section, or the generic 'search' 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?

It gives an explicit when-to-use trigger: "Use for any 'what does the law say' question," which is clear context for an agent facing 24 siblings. It also gives post-call guidance (pass act_id to other statute tools, never hand-build one). However, it never names a when-not-to-use alternative, such as resolve_statute_citation when a citation is already known, so it stops short of the fully explicit routing that earns a 5.

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

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

The description adds valuable behavioral context beyond the annotations: test deliveries are intentionally not persisted, they never appear in list_watch_deliveries, they do not update the watch's last-notified timestamp, and there is a rate-limiting cooldown. This goes well beyond the bare readOnlyHint and destructiveHint values.

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, each carrying distinct information: purpose, persistence behavior, and rate limiting. The main action is front-loaded, and there is no filler or redundancy.

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

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

For a simple one-parameter tool, the description covers purpose, non-persistence, timestamp behavior, and rate limiting. The only notable gap is the lack of any indication about the response format or how success/failure is reported, but the description gives enough context to understand the tool's role and side effects.

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 schema provides only a string-typed watch_id with no description and 0% coverage. The description connects this parameter to 'a watch's destination,' giving minimal semantic context. However, it does not explain the expected ID format, how to obtain a valid watch_id, or any constraints, so it only partially compensates for the missing 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?

The description clearly identifies the action ('send a synthetic notification'), the target resource ('a watch's destination'), and the intent ('verify signing, outbound auth and reachability'). It also differentiates from related tools like list_watch_deliveries by explicitly stating test deliveries are not persisted.

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

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

The phrase 'before relying on it' gives clear timing and use-case context. It also clarifies the behavioral contrast with list_watch_deliveries by saying test deliveries never appear there. It lacks explicit exclusions or alternative tool guidance, but for a focused test operation this is sufficient.

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

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

Annotations already indicate a non-read-only, non-destructive operation, and the description adds useful behavioral context beyond that: pausing via isActive preserves config and history. It also discloses the channel-immutability constraint. No contradiction with annotations.

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

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

Three short sentences, each earning its place: the first states the core action, the second explains the pause behavior, and the third states a key limitation. Information is front-loaded and there is no filler or redundancy.

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

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

For a 7-parameter mutation tool, the description gives a solid overview but omits the scope field, which is a significant modifiable watch property according to the schema. Since there is no output schema and the description is the main selection signal, this omission leaves an identifiable gap, even though the rich param schema partially compensates.

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 high (86%), so the schema already carries most parameter meaning. The description adds mild semantic grouping ('destination, signing secret, outbound auth, or active state') but does not clarify parameter behaviors beyond schema. It also silently omits the scope parameter, which the schema documents in detail.

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 ('Change') and a clear resource ('a watch'), and lists the main modifiable aspects: destination, signing secret, outbound auth, and active state. It also adds a useful limitation ('The channel itself cannot be changed'). However, it omits 'scope' as a modifiable field, so the enumeration is not fully exhaustive.

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

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

The description implies use when modifying watch settings and gives a concrete use case: 'Set isActive false to pause notifications while keeping the watch's config and history.' It also states an exclusion ('The channel itself cannot be changed'). However, it never names alternatives like create_watch, delete_watch, or test_watch, nor does it explicitly say when not to use this tool.

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