Georgia Commons

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

Annotations already mark this as read-only and idempotent, and the description adds meaningful behavioral detail beyond that: the response is windowed by start and max_chars, has a 60,000-character default, and includes a continuation pointer. It does not explain the pointer format, but the added windowing/pagination context is useful.

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

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

A single sentence with no filler; the key return type, windowing behavior, default, and continuation mechanism are front-loaded. 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 and 0% schema description coverage, the description is a reasonable but incomplete specification. It covers the core text-windowing behavior but omits what the continuation pointer looks like, how bill/session should be supplied, and what exact response shape to expect.

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

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

Schema description coverage is 0%, so the description bears the burden of explaining parameters. It does explain start and max_chars, including the 60,000 default, but it leaves bill and session unexplained. This is partial compensation, not complete coverage of the four parameters.

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 tool as returning the stored text of a bill, which distinguishes it from list/search/lookup siblings even though no sibling is named. It lacks an explicit verb but the tool name and noun-phrase description make the operation unambiguous.

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 no guidance about when to use this tool versus alternatives such as bills_lookup, bills_search, or bills_list. There is only an implicit sense that it is for retrieving bill text; no exclusions, prerequisites, or alternative-selection conditions are provided.

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 safety (readOnlyHint, idempotentHint, destructiveHint), so the bar is lower. The description adds useful behavior: newest-when-session-omitted, number ordering, 25-a-page, and subject being a heading search. It doesn't mention pagination mechanics beyond start/limit or rate limits, so a 3 fits.

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

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

One dense sentence front-loads the core behavior (session, ordering, page size) and then lists filters compactly. There is no filler, tautology, or repetition of the tool name.

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 listing tool with no output schema, the description covers the essential call semantics: default session, ordering, page size, pagination params, and filter domains. The only missing elements are an example of a LegiScan status code and explicit pagination continuation behavior, but these are minor for a list call.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it names q, kind, chamber, status, subject, session, limit, and start, and explains the value domains for kind, chamber, status, and subject. Minor gap: q is described as 'words' but exact matching semantics are not clarified.

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+resource: lists bills of a session, with ordering and page size. It distinguishes itself from the sibling `bills_search` by emphasizing a paged list in number order rather than search, and it enumerates filters.

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

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

The description gives clear context on when to use the tool: when you want a paged list of bills in a session, optionally filtered. It does not explicitly name alternatives, but the contrast with `bills_search` is strongly implied by the sibling names and the deliberate 'list' framing.

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 discloses the output format (Markdown with frontmatter, verbatim text, summaries) and the effect of `full`. Annotations already indicate read-only, non-destructive, idempotent behavior, and the description aligns with these, adding detail about the response structure without contradiction.

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 moderately long but well organized around the main purpose and the two optional parameters. There is minor redundancy in listing 'status' twice in the frontmatter/closing phrase, but it does not detract significantly from clarity.

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 three parameters and no output schema, the description sufficiently explains what is returned and how the optional parameters change the result. It omits error behavior or edge cases, but the core usage is well covered.

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 zero descriptions for the parameters, but the tool description covers all three: `bill` (accepted forms), `session` (defaults to newest), and `full` (adds extra content). This compensates well for the missing schema-level 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 resource (a single Georgia General Assembly bill or resolution) and the lookup action implied by the tool name, including accepted formats. It does not explicitly name sibling tools or use a verb like 'retrieve', but the scope is sufficiently distinct.

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 explains the optional `session` parameter (when not the newest session) and the `full` parameter (adds history, votes, amendments), which gives practical usage guidance. It does not explicitly contrast with sibling lookup/search tools, but the parameter instructions are useful.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by noting that search matches document words and that in_headings restricts to titles/topics/subjects. However, it does not disclose return format, pagination, or how results are ordered.

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 purpose front-loaded, then a query nuance and a parameter hint. No filler, each 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?

For a search tool with four parameters and no output schema, the description gives enough to start but leaves limit/session semantics and result structure undefined. It is minimally adequate but not comprehensive.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only covers in_headings; limit and session remain unexplained, and the query parameter is only given phrasing advice rather than format or meaning.

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 performs full-text search over bill text, titles, and labeled summaries, and clarifies direct lookup for bare bill numbers. This distinguishes it from sibling tools like bills_lookup or bills_get_text by emphasizing the full-text scope.

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 guidance on query phrasing ('ask in the words the bill would use') and describes the in_headings behavior, but does not explicitly compare to alternatives or state when not to use it. The hint about bare bill numbers implies direct lookup, but no sibling exclusions are given.

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 indicate read-only, non-destructive, and idempotent behavior, so the bar is lower. The description adds that it returns one line per node with counts and citation spans but does not explain side effects or output format details.

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-loads the key hierarchy levels and examples. It is not verbose, though the phrase 'twin URLs' is ambiguous and could be clarified without much extra length.

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 available sibling tools and no output schema, the description leaves out essential context such as the meaning of 'twin URLs', the exact format of output lines, and how this browsing tool relates to specific lookup tools.

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

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

The single parameter 'node' is shown with default null and a string/null type, but the description only indirectly explains it via examples like '36' and '36-60'. It does not define what values are valid or how null behaves.

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 it browses a hierarchy with titles, chapters, and sections but does not explicitly name the verb as 'browse' nor clarify what 'twin URLs' refers to. It distinguishes from siblings somewhat by mentioning hierarchy levels.

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?

No explicit guidance on when to use this tool versus alternatives like code_describe_structure, code_find_chapter, or code_get_chapter. The description implies browsing but does not state conditions for selection.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds value by noting it is 'Cheap' (low cost) and by describing the type of information returned, which goes beyond the annotations.

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

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

The description is two short sentences with no wasted words. The critical 'Call first' instruction is front-loaded, followed by a compact list of covered topics. It is highly efficient and 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?

For a no-parameter, read-only tool, the description fully explains what the agent will get: grammar, search strategies, version/status semantics, content scope, and title list. It is complete for an agent to decide to call it first without needing additional context.

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

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

The tool has zero parameters, so the description carries no parameter burden. Per guidelines, the baseline for 0 parameters is 4. The description doesn't need to explain any inputs, and it doesn't contradict 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 clearly states a specific purpose: to be the entry point for the Code, providing citation grammar, section-finding strategies, version/status handling, content scope, and title list. This distinguishes it from sibling tools like code_lookup_section or code_search, which are for specific lookups.

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 instruction 'Call first for the Code' is an explicit usage directive, telling the agent to invoke this before any other Code tool. It implies alternatives (specific lookup tools) without naming them, but the 'call first' guidance is strong and unambiguous.

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 discloses what the tool returns (citing section and unit) and the readOnlyHint annotation indicates no side effects. However, it does not mention potential errors, limits, or the exact format of the output, so it is not fully transparent.

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

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

The description is concise but awkwardly phrased as a run-on sentence: 'Laws by the short title the statute states (...): the citing section and the unit the name covers.' It could be structured more clearly while staying brief.

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 lookup with one parameter and no output schema, the description provides adequate context: it states the purpose, the input (short title), and the output (citing section and unit). It lacks explicit details on output format or error handling, but these are not critical for a basic lookup.

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 only parameter 'name' has no description in the schema, and the schema coverage is 0%. The tool description implies that 'name' is the short title, but this is not explicitly stated, so the parameter meaning is not fully compensated for by the description.

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

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

The description clearly states the tool finds laws by short title, providing concrete examples ('Joshua's Law', 'Georgia Lemonade Stand Act') and mentions the output (citing section and unit). This differentiates it from sibling tools like code_search or code_lookup_section.

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 does not explicitly state when to use this tool versus alternatives, but the specific purpose (searching by short title) is clear enough that an agent can infer when it is appropriate. No alternative tools are mentioned.

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 discloses that the tool searches headings specifically, which is a behavioral detail beyond the readOnlyHint and idempotentHint annotations. It also implies a return format that includes the code_browse call, but it does not explain pagination, limit, or exact matching behavior. Since annotations already cover the read-only and idempotent nature, the description adds useful but limited context.

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

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

The description is a single sentence that front-loads the use case and then specifies the search target and result. It is concise with no filler, though the final clause 'with the code_browse call that lists each' adds a slight ambiguity and could be simplified. Overall it is well-structured and efficient.

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

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

For a tool with a single parameter and no output schema, the description covers the core purpose and use case, and differentiates from siblings by emphasizing heading searches. However, it lacks details about the output format (other than mentioning code_browse), edge cases, or any limitations, leaving the agent to guess about response structure and exact behavior. It is adequate for a simple tool 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?

With 0% schema description coverage, the description must clarify the single 'words' parameter. It states that headings 'carry the words', indicating that the parameter is a string of terms to match against headings. This gives basic meaning but omits details like case sensitivity, whether it's a phrase or individual words, and how multiple terms are handled. It is better than nothing but not comprehensive.

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 finds titles, chapters, articles, and parts whose headings contain the given words, and that it pairs each with a code_browse call. It is specific about the resource type (legal code components) and the search scope (headings), which differentiates it from siblings like code_search that might search full text. The phrasing is somewhat awkward but the purpose is unambiguous.

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 opening 'For I know the topic but not the citation' provides a clear use case, indicating when to use this tool: when the user has a topic but lacks a citation. However, it does not explicitly mention alternative tools or when not to use it, leaving the choice of sibling tools like code_search or code_find_act to the agent's inference. It gives context but no exclusions or comparisons.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable operational details: sections are returned in order, results are windowed by max_sections and max_chars, and the output signals continuation with a pointer or 'End of chapter.' This goes beyond the structured annotations.

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

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

The description is a single dense sentence that front-loads the core behavior, then adds windowing defaults and the termination signal. Every clause 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?

The description explains the output shape, ordering, windowing, and continuation behavior, which is helpful given there is no output schema. However, it omits enough parameter semantics for title, chapter, and start, and provides no guidance on alternatives, leaving the definition adequate but not complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the parameter explanation. It explains max_sections and max_chars with defaults and implies start via the continuation pointer, but it does not clarify the meaning or format of title, chapter, or start. With 5 parameters and no schema descriptions, this is a significant gap.

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

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

The description clearly identifies the resource (sections of a chapter) and the operation (returning their text in order), plus the windowing behavior. It does not use an explicit verb, and it does not name sibling tools, but 'every section of a chapter' distinguishes it from more targeted lookup 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?

The description implies this tool is for retrieving all sections of a chapter in sequence, which gives an agent a reasonable sense of when to use it. However, it does not explicitly state when to prefer this over code_lookup_section, code_lookup_sections, or code_find_chapter, nor does it mention alternatives or 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?

The description explains the return format (frontmatter, verbatim text, notes), the effect of the `version` and `subsection` parameters, and the 404 behavior naming neighboring sections. There is no contradiction with the read-only, idempotent 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 brief, but uses odd phrasing such as 'the twin site serves' and 'notes capped', which can obscure rather than clarify. It is not overly long, but the cryptic style hurts readability.

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 lookup tool, the description covers the main resource, parameters, return content, and error behavior. However, the unclear phrasing and lack of explicit usage scenarios leave some gaps in what an agent needs to confidently invoke it.

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

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

Schema coverage is 0%, so the description must carry the explanatory load. It does explain `version` and `subsection`, but the primary `citation` parameter is left undescribed, and no format or example is provided for any 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 clearly identifies the resource as a single Code section retrieved by citation, and contrasts with the plural sibling `code_lookup_sections`. However, it lacks an explicit verb like 'look up' or 'retrieve', relying on the noun phrase 'One Code section by 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?

No explicit guidance is given about when to use this tool versus alternatives. The singular/plural contrast with `code_lookup_sections` is implied but never stated directly, leaving the agent to infer the appropriate selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral details: the 40-section and 150,000-character caps, and the trailer that names anything not rendered. These go beyond the annotation metadata.

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

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

One dense sentence that front-loads the purpose ('Several sections at once'), then packs examples, limits, and trailer behavior with zero filler. Every word earns its place.

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

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

For a single-parameter read-only lookup, it explains input syntax, limits, and partial-rendering behavior. It doesn't detail the exact return format of the sections, but with no output schema and a simple read operation, an agent has enough 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 coverage is 0%, so the description must explain the 'citations' parameter. It does so thoroughly with examples ('44-7-30, 44-7-31 and 44-7-34' or '44-7-30 through 44-7-35'), plus constraints (up to 40 sections, 150k chars). This fully compensates for the schema's silence.

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 multiple code sections at once, with explicit examples of list and range input formats. It distinguishes from the singular sibling code_lookup_section by the plural 'sections' and the batch nature described.

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 clear context that this tool is for retrieving several sections in a single call, implying it is the right choice when you need a batch. It doesn't explicitly name alternatives or exclusions, but the sibling 'code_lookup_section' is an obvious single-section counterpart.

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 discloses detailed ranking behavior (citation returns that section first, act name returns short title section first) and clarifies that matching is on document words. It also explains the in_headings parameter's effect. These go beyond the annotations (readOnlyHint, idempotentHint) and are valuable for predicting search 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?

The description is three sentences, front-loaded with the core purpose. Every sentence adds substantive information: the main search capability, the citation/act behavior, and the in_headings option. No filler or repetition.

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

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

The tool is moderately complex (search with citation handling and in_headings), and while the description covers the query behavior well, it omits any explanation of the 'title' and 'chapter' parameters, which are likely used for scoping. There is no output schema, so the description does not hint at the return format, but the annotations (read-only, idempotent) make it a safe search. The missing parameter explanations leave an agent guessing how to use those filters effectively.

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 description explains the 'query' parameter (words or citation) and 'in_headings' parameter, but it does not explain 'limit', 'title', or 'chapter'. With schema description coverage at 0%, the description must compensate, but it only partially does so. The schema provides types and defaults but not semantic meaning, so the description adds value for two of the five parameters but leaves the others unexplained.

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 performs full-text search of the Code, with a specific resource (the Code) and a specific verb (search). It differentiates from siblings like bills_search and opinions_search by specifying 'the Code'. It also explains the behavior with citations and act names, which is unique to this 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?

The description gives clear context on how to search (using the words of the statute) and what in_headings does, but it does not explicitly mention when to use this tool versus alternatives like code_lookup_section or code_find_act. It implies full-text search is the use case but does not state exclusions or when to prefer a different 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 description mentions an output characteristic ('one line each with twin URLs') but it is unclear and does not clearly disclose behavioral traits beyond what annotations already state. No contradictions exist, but the added transparency is minimal and cryptic.

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 brief, but the structure is confusing and not front-loaded. It mixes a resource description with unclear output details, making it hard to parse quickly. It is concise in word count but not in clarity.

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 appears to be a browsing function for constitutions, the description lacks essential context: what constitutes 'articles and sections', what the 'node' parameter represents, how the output is structured, and how it differs from related tools. It is incomplete for effective tool selection.

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 two parameters (node and scheme) with no descriptions. The description only hints at possible values for scheme ('ga' or 'us') without explaining either parameter's meaning or how they affect the operation, leaving the agent without sufficient guidance.

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 is vague about the action; it describes 'articles and sections of a constitution' but does not state whether this is a browse, fetch, or list operation. The parenthetical '('ga' or 'us')' is ambiguous and the mention of 'one line each with twin URLs' further confuses the purpose.

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?

No guidance is provided on when to use this tool versus alternatives like constitution_lookup, code_browse, or search. There is no indication of when this tool is preferred or what distinguishes it from 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful output-format information ('Markdown twin with the case annotations capped'), but the phrase is somewhat ambiguous and does not explain pagination, errors, or availability limitations.

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

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

A single dense sentence with no filler, front-loaded with the resource and supported by examples. The awkward 'Markdown twin with the case annotations capped' phrase slightly hurts clarity, but the overall structure is efficient.

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

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

The tool has no output schema, so the description must explain return shape; it gestures at Markdown output with capped annotations but remains vague. It also does not define what a slug looks like, leaving a meaningful gap for an agent trying to construct a valid request.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains possible scheme values ('ga' or 'us') and gives concrete citation examples for the citation parameter. It does not fully clarify the slug format, but it provides substantial meaning beyond the bare schema.

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

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

The description names a specific resource (Georgia or United States constitution provisions as printed in the O.C.G.A.), a lookup action, and accepted identifiers (citation or slug). It is distinct from sibling tools like code_lookup_section, though it does not explicitly contrast itself with constitution_browse.

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: use this for constitutional provisions by citation or slug. However, there is no explicit statement of when to prefer this over constitution_browse or other lookup tools, and no 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?

The annotations already declare read-only and non-destructive behavior, and the description adds a performance note ('Cheap'). This is sufficient given the annotations present.

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 short but runs multiple items together in a list-like stream without clear sentence structure. It is not as crisp as a two-sentence summary.

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 description covers the expected outputs (site contents, collections, grammar, next-tool guidance) and includes a cost note. It is adequate for an initial discovery tool, though the phrasing is slightly oblique.

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 no parameters, so there is nothing to explain beyond the schema. The description does not need to address inputs.

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 lists the tool's content (what Georgia Commons holds, collections, id/URL grammar, next tool, independence statement) but lacks a clear verb like 'describes' or 'returns', making the purpose less explicit than a direct statement.

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 'Call first' provides a clear directive on when to use this tool, and mentioning 'which tool to call next' indicates it helps navigate the toolset. However, it does not explicitly contrast with 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?

Adds context beyond annotations: describes the output format (frontmatter, verbatim text, summaries) and the canonical page for citation. Annotations already declare readOnly/idempotent/non-destructive, so the description enriches the behavioral picture without contradiction.

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

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

A single dense sentence that front-loads the main purpose and includes necessary examples. It is efficient but packs a lot of detail in one sentence, which slightly reduces readability while still being appropriately concise.

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, the description covers what is returned (frontmatter, text, summaries) and notes the canonical page. It does not mention error handling for invalid ids, but this is a minor gap for a fetch tool; overall it is complete enough for correct invocation.

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

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

Schema description coverage is 0%, and the description fully compensates by explaining the 'id' parameter with concrete examples of accepted formats and the 'full' parameter as lifting notes cap or adding optional material. This adds essential meaning the schema lacks.

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 (fetch) and resource (full document for an id), with concrete id format examples (code:44-7-34, bill:2025-2026/hb136) that distinguish it from search (which returns ids) and other text tools like bills_get_text or opinions_get_text. It clarifies it returns the Markdown twin of the site page, making its scope unambiguous.

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?

Clearly implies usage after search by saying 'for an id from search', and explains the optional 'full' flag behavior. However, it does not explicitly name alternatives or state when not to use this tool versus siblings, leaving some routing to inference.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is well established. The description adds the useful behavioral note that the data is 'computed from the stores now,' implying a live/current snapshot. However, it does not disclose return shape, pagination, errors, or cost, so its contribution beyond annotations 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?

The description is one tight sentence with no filler. It front-loads the key idea ('Exactly what is loaded') and then compresses the output content into a compact list, earning its place entirely.

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 parameterless read-only tool, the description is fairly complete: it names the substantive output components and the live-computation behavior. However, with no output schema it leaves the response container shape (e.g., object vs. list) and count semantics unspecified, so it is not a 5.

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 confirms this with an empty properties object, giving 100% schema coverage. A zero-parameter tool gets the baseline 4; there are no parameter semantics for the description to clarify.

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

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

The description names the resource ('coverage') and enumerates its contents: coverage sentences, corpus versions, counts, sessions, years, dates, licenses. It is specific about what the tool addresses, but it lacks an explicit verb like 'retrieves' or 'computes' and does not contrast itself with sibling tools.

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

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

There is no guidance about when to use get_coverage instead of the many sibling list/lookup/search tools. The description simply states what is loaded/computed, leaving selection criteria entirely 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description does not need to repeat safety. It adds value by disclosing the windowing behavior (start, max_chars) and the continuation pointer, which are behavioral traits not captured by annotations or schema defaults alone. No contradiction with annotations.

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

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

The description is a single sentence that front-loads the core purpose and includes essential details (windowing and continuation) without any redundant words. It is highly efficient and well-structured.

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 tool with three parameters and no output schema, the description covers the main behavioral aspects: text retrieval, windowing, and continuation. It does not specify the exact format of the continuation pointer or any pagination limits, but these are minor given the tool's simplicity. The annotations cover safety, so the description is largely complete.

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

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

With schema description coverage at 0%, the description must compensate. It explains start and max_chars as windowing controls and notes the default 60,000, but does not elaborate on the opinion parameter beyond its role as the required identifier. The 'pointer to continue' hints at output semantics but does not detail parameter usage further. Partial compensation, but opinion semantics are obvious from context.

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 the tool returns the stored text of an opinion, specifying the windowing parameters and continuation pointer. It is clear and specific, though it does not explicitly distinguish itself from sibling tools like opinions_lookup or opinions_search. The verb is implied (retrieve), but the resource and scope are clear.

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 no guidance on when to use this tool versus alternatives. It does not mention situations where another tool (e.g., opinions_lookup for metadata, opinions_search for discovery) would be more appropriate. The usage context is only implied by the description's focus on text retrieval.

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 behavioral details beyond annotations: default year (newest when omitted), ordering (filing order), and page size (25). It doesn't mention error handling or rate limits but covers key execution behavior for a read-only listing 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 a single, dense sentence with no redundant words. It packs all key information (purpose, fields, ordering, pagination, filters) efficiently without sacrificing clarity.

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 listing tool, the description covers essential context: output fields, default year, ordering, pagination, and filter options. It omits explicit parameter semantics for limit/start, but the tool is straightforward enough that this is a minor gap.

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

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

The schema has 5 parameters, all optional. The description explains q, year, and case_type, but fails to explicitly describe limit and start. The mention of '25 a page' implies a default for limit, but start (offset) is not mentioned at all, leaving its semantics unclear.

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 opinions filed in a given year, with explicit field listing (docket, date, case name, case type, URL), ordering (filing order), pagination (25 per page), and filtering options. No 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?

The description mentions filter options (case_type, q) but does not explicitly compare against sibling tools like opinions_search or opinions_lookup. There is no direct 'use this when...' guidance, leaving the choice to inference from the tool name and context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavior beyond that: it explains that when multiple opinions share a docket, the most recent is returned and the frontmatter lists others, and it describes what the 'full' flag adds (summarized reasoning, checked quotes, CourtListener records). These are useful behavioral details not covered by annotations, with no contradiction.

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 moderately long but every sentence contributes: the first defines the tool and output, the second addresses the multi-opinion edge case, the third explains the 'full' option. It is front-loaded with the core purpose and avoids fluff. Slightly dense but appropriately structured.

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 description covers the input formats, output structure (frontmatter, verbatim, summaries), behavior for shared dockets, and the effect of the 'full' flag. There is no output schema, but the description explains what the response contains. For a lookup tool with two parameters, this is adequately complete; missing error handling is not a significant gap.

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

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

Schema description coverage is 0%, so the description must carry the burden. It explains the 'opinion' parameter accepts docket numbers, citations, CourtListener IDs, or case names, and it explains the 'full' parameter adds extra content. This provides meaning beyond the bare schema types, effectively compensating for the lack of schema descriptions.

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

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

The description clearly states the tool retrieves a single Supreme Court of Georgia opinion by various exact identifiers (docket, citation, CourtListener id, case name). It specifies the output format (Markdown twin with frontmatter, verbatim opinion, summaries) and distinguishes from siblings like opinions_search by focusing on exact lookup. The verb 'lookup' plus resource 'opinion' is specific and unambiguous.

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 the tool is for exact identifier lookups but does not explicitly mention when to use it versus alternatives like opinions_search or opinions_get_text. It does not state 'use this when you have a specific identifier, otherwise use search.' The context signals list siblings, but the description itself offers no direct comparison or exclusion guidance, so usage guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds that search matches literal words of the document (not semantic meaning) and that in_headings scopes to case names, legal areas, and case types. This adds some behavioral context beyond annotations, but does not disclose pagination, result format, or other operational details.

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 sentences, front-loaded with the primary purpose, followed by a direct-lookup note and a query tip. Every sentence adds relevant information without waste. The structure is logical and easy to scan, though it could be slightly more compact.

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 and 0% parameter coverage, the description is the only source of guidance. It does not describe what results look like, how pagination works, or how to combine parameters effectively. Given the tool's complexity (5 params, no output schema), this is inadequate for an agent to invoke it correctly without further discovery.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions query implicitly via the search behavior and explains in_headings, but does not describe year, limit, or case_type. While these parameter titles are somewhat self-explanatory, the description fails to clarify their allowed values or how they interact, leaving the agent with insufficient guidance for a 5-parameter tool.

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 performs full-text search over opinion text, case names, and labeled summaries, and explicitly differentiates it from a direct lookup. This is a specific verb-resource pair that distinguishes it from siblings like opinions_lookup and opinions_list, leaving no ambiguity about its core function.

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 offers a query-formation tip ('ask in the words the court would use') and notes that a bare docket or citation is a direct lookup, but it does not explicitly state when to prefer this tool over siblings like opinions_lookup or opinions_list. No exclusions or alternative-selection guidance is provided, leaving the agent to infer usage context.

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 is transparent about returning up to ten results, matching the words of the document, and following up with fetch(id). The readOnly and idempotent annotations are consistent, and the description adds useful behavioral detail beyond the annotations.

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

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

The description is concise and front-loaded with the primary behavior, output limit, and result shape. The last two sentences are slightly redundant but still add useful usage guidance, so 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?

The description gives enough context for an agent to call the tool correctly: query, optional collection, result count, result fields, and the next fetch step. It does not cover invalid-collection behavior or sorting, but for a simple search tool with an output schema this is reasonably complete.

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

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

With zero schema description coverage, the description compensates by explaining `collection` values (code, bills, opinions) and clarifying that `query` should use the document's wording. It could include examples or explicit limits, but it provides sufficient meaning for both parameters.

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 action ('Search'), the target resource ('every loaded collection' or one specified by `collection`), and the output shape. It distinguishes this generic tool from collection-specific siblings by emphasizing cross-collection search.

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

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

The description gives useful guidance on query phrasing and the optional `collection` scoping, and it mentions prioritizing citations/bill numbers/dockets. However, it does not explicitly explain when to use this tool instead of the sibling collection-specific search tools such as bills_search, code_search, or opinions_search.

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

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

Beyond the read-only and idempotent annotations, the description discloses determinism and the normalization rules (quotes, dashes, whitespace, [T]he-style alterations). It does not specify the exact return value (e.g., boolean vs. error), but the core behavior is transparent.

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

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

The description is a single, focused sentence with no fluff. It efficiently conveys the purpose, normalization details, and determinism in a compact form.

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 simple two-parameter signature and the presence of an output schema (not shown), the description covers the essential aspects. The return type is implied ('whether'), and the context of use is clear enough 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?

The schema provides no parameter descriptions, so the tool description must compensate. The names 'id' and 'quote' are reasonably self-explanatory, and the description implies their roles, but the mapping is not explicitly stated. This leaves some ambiguity for an agent.

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

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

The description clearly states the tool's function: verifying whether a quote appears verbatim in a document's text. It distinguishes itself from sibling tools by being the only verification tool, and the normalization details further clarify its exact 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?

The description explicitly advises using this tool before relying on a quotation, providing a clear usage context. It does not enumerate alternative tools, but the unique purpose makes the appropriate use evident.

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