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

Annotations include readOnlyHint=true, and the description reinforces that it only returns field information, which aligns. It does not describe the output format or any potential limitations (e.g., whether the field list is exhaustive or versioned), but for a zero-parameter read-only tool, the description is adequate. No contradiction found.

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

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

The description is compact and well-organized: a clear primary statement, a block of alternative search terms, a 'Use for' section, and a 'Returns' statement, all in a few sentences. It ends with a pointer to a sibling tool, making every sentence earn 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 zero-parameter, read-only tool, the description fully covers what the agent needs: purpose, usage scenarios, output, and differentiation from alternatives. The output schema is present, so no need to describe the return structure in detail. The guidance to another tool for advanced syntax is a bonus.

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 no parameters, and the description clarifies what the tool returns ('Complete field list with descriptions and types'). Since there are no parameters to document, the description provides sufficient context about the output, which adds value beyond 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 the tool retrieves searchable fields from the USPTO Enriched Citation API, with a specific verb 'Get' and resource. It includes synonyms and use cases, making it distinct from siblings like Citations_get_oa_citation_fields and Citations_get_guidance, though it doesn't explicitly contrast with these.

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 lists when to use: 'Use for: Field discovery, query syntax validation, understanding data structure.' It also gives an alternative for 'field selection strategies and Solr/Lucene syntax examples' by directing to Citations_get_guidance(section='fields'), making the distinction clear.

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 adds the important behavioral limitation that it returns citation metadata only and NOT actual documents. It also provides a concrete 2-step workflow for retrieving document content and downloads through related tools, which meaningfully discloses what this tool does not do and how to supplement it.

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 opening sentence is clear and front-loaded, but the description repeats the 'full record' idea and includes a long PFW workflow and document code decoder that are tangential to this tool's immediate invocation. The content is structured, but much of it could be moved to guidance content rather than the tool description.

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 tool's primary caveat and cross-tool workflow, and an output schema exists, so return structure does not need to be explained. However, it omits explicit parameter semantics and does not clearly guide the agent from a search result to this tool's citation_id input, leaving some context incomplete.

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

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

There is zero schema description coverage, and the description does not explain citation_id or include_context. The parameter names are somewhat self-explanatory, but the description fails to compensate for the missing schema details, especially what include_context toggles or how the ID should be supplied.

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 complete details for a specific citation by ID, enumerates the content returned (all fields, cited passage, locators, figure, mapped claim, quality summary), and distinguishes it from the sibling search tools by focusing on ID-based retrieval.

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 for deep analysis of strategically important citations and makes clear it is for looking up an existing citation by ID. It does not explicitly contrast with sibling search tools or state when not to use it, but the intended use case is clear.

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 important behavioral traits: criteria is validated against an enriched field whitelist, OA-only clauses cause a 400, there is no lane parameter, and the OA index has no statistics path. It also states the returned fields for the enriched lane. This goes well beyond the annotation and gives the agent an accurate model of the tool's behavior and constraints.

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 longer than average, but every section earns its place: purpose, lane limitation, workaround, and return summary. The bold ENRICHED LANE ONLY warning is front-loaded, and the example is compact and directly useful. Given the complexity of the lane distinction, the length is appropriate 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?

With one optional parameter, an output schema, and readOnlyHint already present, the description covers the essential contextual gaps: what the tool aggregates, what lane it targets, what happens on invalid criteria, how to handle the OA lane, and what the return shape is. The agent has enough information to select and invoke this tool correctly in almost any scenario.

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 'criteria' string with a default of '' and zero description coverage, so the description carries the full burden. It does explain that criteria is validated against the enriched field whitelist and gives an example query ('techCenter:2100 AND legalSectionCode:103'), but it does not fully define the general query syntax or what an empty default means. Still, it adds 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 opens with a clear verb and resource: 'Get database statistics and aggregations for strategic planning.' It then enumerates what counts as statistics (counts, totals, aggregate, distribution, breakdown by art unit/tech center, trends over time, citation volume), which sharply distinguishes it from sibling search tools. This makes it immediately clear this is an aggregation tool, not a search or details 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 explicitly states 'ENRICHED LANE ONLY' and explains when to use an alternative: 'To aggregate the OA lane, count it yourself with the OA search tools.' It even provides a concrete example call and explains the limitation is 'a documented limit, not a bug to work around by rephrasing the clause.' This is model usage guidance with both when-to-use and when-not-to-use.

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 declare readOnlyHint=true, and the description consistently reflects a read-only documentation tool with no destructive behavior. It adds useful behavioral context by listing available sections, indicating PTAB content was updated on 2026-01-17, and noting that sections are retrieved selectively for context-efficient workflows.

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 well-organized and front-loaded with a clear purpose, but it is longer than necessary and contains redundancy: the quick-reference section, the 'Available sections' list, and the later detailed bullet list overlap significantly. The emoji formatting helps scannability but does not fully justify the 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?

For a low-complexity tool with one optional parameter, a readOnlyHint annotation, a fully documented schema, and an output schema, the description is complete. It lists every available guidance section, explains what each covers, and gives enough context for an agent to select the right section and invoke the tool successfully.

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 the single 'section' parameter at 100% coverage, but the description adds substantial meaning by enumerating all valid section values, their purposes, and the default 'overview'. Since the schema has no enum, this enumeration is valuable beyond what the schema provides.

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

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

The opening sentence uses a specific verb ('Get') and resource ('selective USPTO Citation guidance sections'), and the quick-reference table clarifies it is a documentation/guidance tool rather than a data-retrieval tool. However, it does not explicitly contrast itself with the sibling search/data tools, so an agent might initially wonder whether 'guidance sections' is a search operation.

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 quick-reference list maps user intents to specific sections (e.g., 'Which lane: OA citations or enriched citations?' → oa_citations), which gives strong in-tool usage guidance. It lacks explicit exclusions or instructions about when to use a sibling search tool instead, but the guidance-vs-search distinction is largely implied by the content.

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 include readOnlyHint: true, which the description aligns with by stating it 'Returns the complete field list' – no mutation. The description adds context about the data source (raw citation data from Form 892 and Form 1449) and the lane distinction, which is useful beyond the annotation. However, it doesn't disclose any specifics about output format, pagination, or error behavior, which is acceptable for a simple metadata retrieval but not rich in additional 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?

The description is redundant in places: 'Fields, available fields, columns, schema, what can I query, field names, query syntax for the OA citations lane' is a list of synonyms that could be condensed. The core information is in the first sentence and the following two sentences, but the initial repetition adds noise. It's not extremely lengthy, but it could be more 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?

For a tool with no parameters and an output schema (known to exist, though not provided), the description covers the essential context: it states the resource (OA Citations API v2), the purpose (return field list for Lucene queries), the lane distinction (vs AI-enriched), and the data source (Form 892/1449). This is sufficient for an agent to understand when and how to use it, leaving little 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters because there are none, and the schema coverage is 100% (vacuous). The description does explain that it returns a field list, which is the only meaningful semantic context, but it doesn't need to compensate for any parameter documentation gaps.

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 'Get all searchable fields from the USPTO Office Action Citations API v2' and specifies its purpose: returning the complete field list for building Lucene queries. It distinguishes itself from the generic sibling 'Citations_get_available_fields' by noting that it targets the OA Citations lane and contrasts with the AI-enriched citations. This gives a specific verb, resource, and 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?

The description implies when to use this tool: for retrieving field information specifically for the OA Citations v2 dataset, as opposed to the AI-enriched citations. It mentions 'simpler counterpart' and 'provides raw citation data from Form 892 and Form 1449,' which helps an agent choose this tool over the generic 'Citations_get_available_fields.' However, it doesn't explicitly state when not to use it or name direct alternatives, so it's clear but not exhaustive.

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 only readOnlyHint=true as an annotation, the description carries the full burden of behavioral disclosure, and it does so extensively. It discloses date handling quirks (documented window vs actual practice), the behavior for rows without a reference identifier (must be reported as unresolved, never dropped), the cross-lane join key semantics, error responses for invalid patent numbers, and the ultra-minimal mode. There is no contradiction with the read-only 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?

The description is long and dense, but it is well-structured with clear sections (Solr examples, convenience parameters, join key, identifiers, limitations) and front-loads the core purpose and usage. Every sentence contributes essential information for a complex 14-parameter tool, though some redundancy exists in the referenceKey and rows-without-reference sections. It is not concise in absolute terms but is appropriately sized for the complexity.

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 (14 params, output schema present, many edge cases), the description is remarkably complete. It covers the purpose, usage, error handling, data quirks, integration with sibling tools and PFW MCP, and even explains the output envelope (rows_without_reference_identifier). Nothing an agent needs to invoke it correctly or interpret results 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 0%, so the description must compensate for all parameters. It explicitly explains convenience parameters (decision_type, category_code, examiner_cited, art_unit), patent_number vs application_number resolution, and provides Solr query examples for criteria and fields. It also notes that applicant_name queries silently return 0 and examinerNameText is not searchable. This adds 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 clearly states the tool's function: a balanced citation search for analysis with 80-85% context reduction, and enumerates the types of data it retrieves (prior art references, passages, locators, claims, etc.). It distinguishes itself from sibling tools like the minimal search and the OA lane, explicitly positioning itself as the follow-up to minimal search for detailed study of 10-20 results.

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 when-to-use guidance: 'Use after minimal search for detailed study of selected citations (10-20 results)'. It also names alternatives: for office action text use PFW MCP's get_oa_text/get_oa_rejections, for complex workflows use Citations_get_guidance(section), and for examiner/applicant resolution use the PFW MCP. It clearly states what is NOT searchable and the consequences (400 vs silent 0), giving unambiguous routing.

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 substantial behavioral edge cases: documented date windows that don't match actual index contents, referenceKey normalization differences, null/missing identifier handling, 400 responses for unresolved patent numbers, and the fact that rows without references must be preserved. It also clarifies the response envelope includes rows_without_reference_identifier. These are exactly the non-obvious behaviors an agent needs to know.

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

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

The description is long but every section earns its place: query examples, date-window caveat, lane routing, cross-lane join key, null-row handling, identifier resolution, and cross-MCP integration. The most important purpose and usage guidance are front-loaded, and the internal headings make the density navigable. There is no filler or repeated schema 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 12 parameters, zero schema descriptions, and the presence of an output schema, this description is exceptionally complete: it covers query syntax, field selection, identifier resolution, error behavior, cross-tool routing, and data-quality pitfalls. The output schema already covers return shape, so the description need not restate it. An agent has enough context to call this tool correctly in a wide range of discovery workflows.

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 carries the full burden, and it does add meaning for the hardest parameters: criteria (Solr/Lucene syntax with examples), fields (custom field list and token reduction), patent_number, and application_number (resolution, crosswalking, 400 behavior). It does not explicitly document rows, start, date_start, date_end, art_unit, tech_center, applicant_name, or examiner_cited, though several are inferable from examples or names. This is strong but not exhaustive.

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 action and resource: 'Minimal citation search for discovery' with an explicit 'Essential 8 fields' list. It also distinguishes itself from the OA lane by labeling this the 'ENRICHED lane' and naming the sibling tool to use for raw OA citations. The purpose is concrete and not a tautology of the tool name.

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 for high-volume pattern discovery before detailed analysis.' It also provides strong when-not guidance, such as 'Do NOT add a blanket officeActionDate:[2017-10-01 TO *] clause' and 'For completeness-sensitive questions also run Citations_search_oa_citations_minimal ... and union the results.' It further routes office-action-text requests to PFW tools, making alternatives clear.

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 only declare readOnlyHint=true. The description adds extensive behavioral context: partial applicant-cited coverage with concrete patent metrics, the cross-lane join key (referenceKey), the documented time window, the deliberate HTTP 400 for publicationNumber, and the patent_number crosswalk behavior. No contradictions.

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

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

The description is front-loaded with purpose and placement, then organizes critical caveats into distinct sections. It is verbose, but each section addresses a unique concern (coverage warning, join key, window, 400 behavior, identifier rules) that materially affects correct use. The length is justified by the tool's complexity.

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?

Covers all essential operational details: the 16 fields, the unique analytical fields, the partial coverage caveat with evidence, the join key, the time window, the deliberate 400 behavior, and the patent_number resolution. With an output schema present, an agent has everything needed to call it correctly and interpret results.

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 compensates well for the ambiguous parameters: patent_number (crosswalk to application serial), application_number (application serial), parsedReferenceIdentifier (join key usage), and criteria (publicationNumber refusal). It does not explicitly explain rows, start, fields, art_unit, tech_center, or examiner_cited, but these are self-evident from names and defaults. Overall strong compensation for the high-stakes 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?

Clearly states it searches Office Action Citations (v2) with all 16 fields, and positions itself as the detailed tier after the minimal search. It distinguishes from siblings by naming the unique analytical fields (legalSectionCode, actionTypeCategory, paragraphNumber) and by referencing the enriched lane.

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

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

Explicitly says to use after Citations_search_oa_citations_minimal for detailed analysis, and gives alternatives: use Citations_search_citations_balanced for pre-grant publications, and use PFW MCP for complete 1449 records. Also warns about partial applicant-cited coverage, guiding when not to rely on this lane.

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 only readOnlyHint=true in annotations, the description carries the full burden of behavioral disclosure, and it excels. It reveals significant caveats: partial applicant-cited coverage (with specific measured examples), the absence of a date field (officeActionDate returns 400), the deliberate rejection of publicationNumber in criteria, the referenceKey join mechanism, and the meaning of createDateTime. No contradiction with annotations; the read-only nature is consistent.

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 long, but it earns its length given the tool's complexity (9 parameters, many pitfalls). It uses clear section headers (warning symbols, query examples, identifiers) and bullet-like structure, front-loads the purpose, and avoids redundancy. It is not perfectly concise—some caveats could be tightened—but it is well-organized and every paragraph adds value.

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 9-parameter schema with zero descriptions, the presence of an output schema, and the intricate domain (patent citations), this description is exceptionally complete. It covers coverage limitations, cross-lane join keys, absence of date fields, publicationNumber handling, identifier semantics, and sibling routing—so nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema coverage is 0% (no parameter descriptions), so the description must compensate—and it does comprehensively. It explains `criteria` with five concrete Solr query examples, defines `patent_number` as a crosswalked granted patent number (with accepted formats and error behavior), clarifies `application_number` as the application serial, and notes that `fields` is ignored by the OA API and the 8-field set is enforced client-side. Every parameter is given practical 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?

The opening sentence states a specific verb ('Search'), a precise resource ('Office Action Citations (v2)'), and the use case ('high-volume discovery (8 key fields)'). It further distinguishes from siblings by naming the balanced and minimal tiers, and explicitly notes the 8-key-field limitation. The purpose is unmistakable even without reading the schema.

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

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

The description explicitly tells when to use this tool and when to use alternatives. It advises running BOTH this lane and the enriched lane for completeness-sensitive questions, states 'Use Citations_search_oa_citations_balanced for full 16-field detail' and 'Use Citations_search_citations_minimal for passage locations, claim mapping, NPL flags, or date filtering', and even suggests defaulting to running minimal alongside. This is exemplary 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?

Annotations already mark this as read-only. The description adds useful behavioral context: it performs a dry-run validation rather than executing a search, and it returns optimization suggestions. This aligns with readOnlyHint and clarifies the side-effect-free nature.

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

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

The description is front-loaded with the core action and then uses examples to make Lucene syntax concrete. It is slightly long, but the example list earns its place for a validation tool where syntax is the main concern.

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, output schema, and sibling context, most of what an agent needs to invoke the tool is present. The main gap is the undocumented 'field_set' parameter, which the description neither defines nor illustrates.

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 has 0% description coverage, so the description must explain the parameters. It thoroughly explains the 'query' parameter with Solr/Lucene syntax examples, but it never mentions the 'field_set' parameter or its allowed values/meaning, leaving a real 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 opens with a specific verb+resource: 'Validate Lucene query syntax and provide optimization suggestions.' This clearly distinguishes it from sibling search/guidance tools and includes concrete examples of what the tool accepts.

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 lists likely user intents ('Check my query, syntax error, is this query valid, ... dry run before searching, why did my search fail') and tells the agent to use Citations_get_guidance for a comprehensive syntax guide. It does not explicitly say when not to use it in favor of a search tool, but the validation context is clear.

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