ca-rate-filings

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

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true. The description goes far beyond these by disclosing the response structure, the 2000-char chunk cap, the behavior for filings without correspondence (returns empty structure, not an error), the grouping/ordering logic, and the three attachment types. This is comprehensive behavioral transparency that adds significant value over 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 lengthy but well-structured with headings, bullet points, and examples. The core purpose and alternatives are front-loaded, and each section (examples, technical details, coverage notes, return shape) serves a distinct purpose. Some redundancy exists, such as the 'Right questions' list partially duplicating the opening statement, but overall it is efficiently organized for an agent to parse.

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 this complexity (multiple attachment types, grouping, chunk caps, empty coverage, return shape), the description covers all necessary aspects: purpose, usage boundaries, technical behavior, coverage caveats, and alternatives. Even without an output schema, the return structure is fully spelled out with field names and types. Nothing an agent needs to call it correctly is missing.

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

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

The input schema already fully documents the `serff` parameter (100% coverage), including its format, validation regex, and error handling for invalid values. The description does not add any additional semantic context for the parameter itself; it only mentions 'given SERFF' in passing. Since the schema carries the full burden, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'see the REGULATORY POSITION history of a filing — the whole CDI ↔ carrier dialogue plus filer contact info — in order.' It explicitly distinguishes itself from content-related tools by naming specific alternatives (get_filing_summary, get_filing_source_file_link, search_filing_embeds) and provides concrete example questions. This is a specific verb+resource+scope with strong sibling differentiation.

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 what the tool is NOT for and routes to alternatives ('NOT for the filing's content, rates, or forms. Content questions live in get_filing_summary...'). It also provides 'Right surface for' scenarios and a pairing recommendation with search_correspondence_embeds, plus a note about the more comprehensive get_filing_dossier. The usage guidance is thorough and actionable, leaving no ambiguity about when to use vs alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral detail beyond annotations: it reveals that the tool composes four sub-fetches in parallel, that failures are isolated per-section with an 'error' field, and that a derived at-a-glance block is included. This materially helps an agent predict partial-failure behavior and response structure.

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?

Although long, the description is tightly structured: bolded core purpose, bulleted example questions, a clearly marked 'Wrong surface for' section, and a compact return-shape line. Every sentence earns its place, and the most important guidance is front-loaded before alternatives and exclusions.

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 composite tool with one parameter and no output schema, the description is complete: it names the composed tools, the returned top-level fields, the derived block contents, failure isolation behavior, and exclusions. An agent has everything needed to decide when to call it and what to expect back.

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

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

Schema description coverage is 100%, so the schema already fully documents 'serff' including format, validation regex, and error behavior. The description reinforces that the tool takes one SERFF id and composes over it, but does not need to add meaning — the baseline of 3 applies since the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb and resource: 'see the full REGULATORY POSITION of a filing' and enumerates exactly what that includes (CDI status, reviewer, objection history, filer contacts, lineage). It also explicitly distinguishes itself from rating-mechanics tools by naming what it is NOT for, making sibling differentiation immediate.

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 when-to-use ('Use this to see the full regulatory position...') and explicit when-not-to-use ('NOT the tool if the question is about rating mechanics... For those, chain into get_filing_summary...'). It further lists 'Wrong surface for' search and caseload scenarios and names the correct starting tools, leaving no ambiguity about 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?

The description adds behavioral context beyond annotations, such as walking back from any SERFF in a program's chain, returning an error if not resolved, and noting possible non-rate-affecting types. No contradiction with annotations (readOnlyHint, idempotentHint).

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-structured and front-loaded with the main purpose, followed by differentiation from siblings and additional usage details. Each sentence adds value without redundancy.

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

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

The description covers the return structure (chain entries with SERFF id, position, role, lite filing record), error handling, and relationship to sibling tools. Given the single parameter and no output schema, it provides sufficient context for an AI agent.

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

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

Schema coverage is 100% with a detailed parameter description including regex validation and error envelope behavior. The description does not add significant new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns the reconciled lineage chain for a SERFF id, specifying the verb 'returns' and the resource. It explicitly distinguishes itself from the sibling get_filing_references by noting the difference between canonical chain and carrier-stated lineage.

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 guidance on when to use this tool ('when you want the canonical chain') versus when to use get_filing_references. It also suggests pairing with search_filings using predecessor_prefix, and explains the error case for unresolved SERFF ids.

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. The description adds that data is extracted from inside the PDF (carrier-claimed), that entries include specific fields, and that an error is returned if no record exists. This goes beyond the annotations, though not exhaustively.

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-structured with clear sections (what it does, distinction, use cases, error handling). Slightly verbose but every sentence adds value; no fluff.

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

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

Despite no output schema, the description explains return format (list entries with specific fields and an error case). Given the tool's moderate complexity and rich input schema, this is adequately complete.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions the parameter shape (PREFIX-IDENTIFIER) and regex validation, which is already in the schema. No additional semantic value 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 description specifies the exact resource returned (predecessor/superseded/companion filings cited by this filing) and distinguishes from the sibling tool get_filing_lineage, using concrete examples like 'supersedes XXXX-NNNN'.

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 compares to get_filing_lineage, explaining when each is appropriate ('carrier's stated lineage' vs 'reconciled chain'). Provides specific use cases: 'what does this filing claim to replace?' and 'which bureau filing did this carrier adopt?'.

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 annotations (readOnlyHint=true), describes link expiry, bypassing Cloud Run, dynamic whitelist, and return fields including a notice. No contradictions; adds substantial behavioral 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?

Well-structured with bold directives and separate paragraphs. Slightly verbose but each sentence adds necessary context. Front-loaded with critical don't-fetch instruction.

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?

No output schema, but description lists all return fields and explains error condition (403 after expiry). With 3 params fully covered and clear workflow pairing, it is complete for a URL-minting tool.

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

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

Schema covers all 3 params (100%). Description adds value by clarifying file_name must be a basename from the listing and ttl_seconds defaults/caps. Does not merely repeat 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 explicitly states the tool returns a short-lived V4-signed GCS URL for a single source file (PDF/XLSM etc.) and distinguishes it from the sibling 'list_filing_source_files' by noting the workflow: discover files first, then call this.

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 explicit 'CRITICAL: DO NOT fetch this URL yourself' directive and explains pairing with list_filing_source_files. Also advises including the expires_at timestamp so the user knows the link's validity period.

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 and idempotent behavior; the description adds that it returns an error if no summary exists, typical response size, and use of page citations. This provides useful context 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, front-loads the main purpose, and uses formatting (bold, bullet points) to improve readability. A few sentences efficiently convey necessary 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 no output schema, the description outlines the return structure (sections, error envelope) and provides enough detail for an agent to understand what the tool provides. It covers key behaviors like error handling and citation format.

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

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

Schema coverage is 100% with a good parameter description; the description adds validation details (regex pattern) and error handling for invalid values, which enriches 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 returns an actuarial narrative summary for a single SERFF id, listing specific sections like Filing Type and 'What This Filing Does'. It distinguishes from siblings by calling it the 'fastest route' and noting the response size, making the purpose 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?

It specifies when to use (when you have a SERFF id and want to understand changes) and provides fallback tools (list_filing_source_files, mcp_health) for missing summaries, advising not to retry. However, it does not explicitly contrast with other sibling tools like get_filing_extracts.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context: it is a single indexed aggregate with one join, no LLM, sorted by filings_total descending, and it precisely defines how filings_closed, filings_pending, and filings_other are computed from serff_filing_status. This goes well 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 long but tightly organized: purpose, exclusions, example questions, cost, and output semantics each earn their place. The most important scoping information is front-loaded, and the examples are concrete and directly actionable.

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

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

With no output schema, the description fully explains the return row shape, status classification logic, sorting order, and topK behavior. It also covers cost and the absence of LLM processing, leaving no critical gap for an agent deciding whether and how to invoke this tool.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds extra value by showing realistic parameter combinations (e.g., email_domain='insurance.ca.gov' + year=2026, email='jane@wps-inc.com', topK=50) and explaining what each row means, which helps an agent construct correct calls.

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 and resource: 'size up a person's REGULATORY caseload' with counts split by filing status. It explicitly distinguishes itself from content/rating tools and names sibling tools it is not, so an agent can select it correctly without opening schemas.

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

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

The description gives explicit when-to-use guidance with concrete example questions and parameter mappings. It also states when NOT to use it and names the correct alternatives (`search_correspondence_embeds`, `get_filing_correspondence`), including how to chain from caseload results to actual filings.

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

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

Annotations declare readOnly/readOnly and idempotent; description adds return metadata details, error envelope for missing files, and parameter validation pattern, going beyond 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?

Well-structured with bullet points, front-loaded with key action, and every sentence adds value without redundancy.

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

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

For a single-parameter, no-output-schema tool, description fully explains return values, error behavior, and relation to sibling tool, leaving no gaps.

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

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

Schema coverage is 100% with detailed description of serff parameter; description reiterates validation but adds no new meaning beyond 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 lists source files for a SERFF id, specifies file types (PDFs, XLS, DOC, ZIP), and distinguishes from sibling tool get_filing_source_file_link.

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 explicit use cases (triage, discover, confirm) and pairs with get_filing_source_file_link for download, giving clear when-to-use and 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?

Annotations already provide readOnlyHint and idempotentHint. Description adds quota-exempt status, null returns for missing fields, and role as identity probe. These are valuable behavioral details beyond annotations.

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

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

Three sentences, each adding essential info: what it returns, quota-exempt, null handling, and typical use case. No wasted words. Front-loaded with key point.

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?

No output schema, but description enumerates returned fields and explains null behavior. For a simple identity probe, this is complete enough. Could mention authentication context, but annotations may imply 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?

No parameters exist. Baseline for 0 parameters is 4. Description does not need to add parameter semantics. It correctly notes no parameters are needed.

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

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

Description specifies it returns resolved identity fields (email, company_name, account_type, company_reference). The verb 'returns' plus resource 'identity' is clear. No sibling tools overlap with account info, so it is well-distinguished.

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 states it is useful as an identity probe without burning quota. Implies usage context (confirming identity). Could be more explicit about when not to use, but given distinct purpose and siblings, guidance is adequate.

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

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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint false, so the safety profile is established. The description adds useful context beyond that: it returns plain-text instructions, is quota-exempt, and includes specific auth-flow expectations. It does not contradict 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 compact and front-loaded: a headline phrase, the core output, the actionable instructions, and the trigger condition. Every sentence contributes unique value, and the most important guidance appears before the details.

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, no-output-schema, self-serve guide, the description covers all the essentials: what it returns, how to interpret the auth flow, the per-client URLs, and when to invoke it. There is no residual ambiguity that structured fields would need to resolve.

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 parameters, the schema is fully covered and there is nothing to add about parameter meaning. The description instead clarifies the return content and auth flow, which serves the parameterless tool well. The baseline of 4 for no-parameter tools is appropriate.

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

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

The description names a clear resource (onboarding + connection guide) and a specific verb (returns plain-text instructions), then itemizes exactly what the instructions cover: signup, client credentials, and per-client walkthrough URLs. It also explicitly states the purpose is to help users get set up, which distinguishes it from the filing/search siblings.

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

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

It gives an explicit when-to-use trigger: 'call this whenever a user asks how to use this MCP, get set up, or connect a new client.' It also highlights that the tool is quota-exempt, which is a concrete consideration for tool choice. No alternative tool is relevant here, so no exclusions are needed.

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 the tool is read-only, idempotent, and not open-world. The description adds behavioral details about the snapshot contents (build info, tool names, hash, data watermark). It does not contradict annotations and provides useful context beyond what annotations convey.

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

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

The description is a single, well-structured sentence that efficiently conveys purpose, contents, and usage. Every clause adds value with no extraneous words.

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?

Despite having no output schema, the description lists all returned fields (build identifier, server_version, boot time, tool names, hash, corpus_updated_at). The guidance on how to interpret results (comparing versions and hashes) makes the tool self-sufficient and complete for its diagnostic role.

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 zero parameters, and the schema description coverage is trivially 100%. No parameter explanations are needed. The baseline for zero-parameter tools is 4 per guidelines.

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 explicitly states it provides a 'Diagnostic snapshot of the deployed MCP server' and lists specific returned fields (build identifier, server_version, boot time, etc.), which distinguishes it clearly from sibling tools focused on filings, products, and searches.

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 guidance: 'Call this first when you suspect the connector is showing a stale tool list or you want to detect whether code or data has changed since your last call.' It also explains what to compare (tools_advertised, server_version, corpus_updated_at), providing clear context for when to use it.

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 bar is lower. The description still adds meaningful behavior beyond annotations: cost model, no LLM planning/composition, coverage caveats about 2026 backfill, cosine similarity semantics, and the first-800-chars excerpt limit. This is rich, non-contradictory 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 long but every section earns its place: purpose and cost are front-loaded, sibling differentiation is explicit, and the bullet lists are dense examples rather than filler. Headings make the structure scannable for an agent.

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

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

With no output schema, the description supplies the return shape explicitly: top-K hits with {serff, similarity, excerpt, meta}. It also covers coverage limitations, how to combine with search_filings and get_filing_summary, and when not to use the tool. Given the 13-parameter complexity and rich sibling set, nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter detail. The description does reinforce query behavior and topK defaults, but most of those facts are already present in the input schema (e.g., topK capped at 50, serff singleton, CA-only state). It adds routing context rather than new parameter-level 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 first sentence names the exact resource and operation: pure vector search over per-filing actuarial-memorandum embeddings. It explicitly contrasts with search_summary_embeds and search_filing_embeds, and clarifies this tool is for actuarial numerics rather than content or filtering.

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 has dedicated 'right tool', 'wrong surface', and 'how to combine' sections. It lists concrete actuarial topics that should use this tool, explicitly routes content queries to search_summary_embeds and filter queries to search_filings, and gives worked combination examples. An agent can not only choose this tool but know when to route elsewhere.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and the description adds substantial context beyond them: the pure vector-search mechanics, that excerpts ARE quotable source text, cost characteristics ('one query-embedding call + one indexed Postgres lookup'), the topK cap, and the critical sparse-coverage caveat that email/email_domain facets match only a minority of chunks. This materially shapes how an agent uses the 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?

Front-loaded with purpose and usage, and well-organized with bold headers and distinct Right/Wrong tool sections. It is long, but every section carries decision-relevant information — routing, facet semantics, coverage caveats, and concrete example queries — so the length is earned rather than padded. Slightly over-built for a search tool, hence 4 not 5.

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?

No output schema exists, so the description correctly carries the burden of explaining return values: 'Returns top-K chunks with {serff, source_file, chunk_index, similarity, excerpt, emails, email_domains, page_date, meta}. Default topK=10, max 50. Excerpt is the first 1200 chars.' For a 16-param tool with heavy sibling differentiation needs, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains how facets combine ('all combine with AND on top of the semantic ranking'), gives the sparse-coverage caveat for email filters, and specifies query semantics ('Pass the user's question verbatim — short, specific 5-30 words matches best'). Does not fully restate every parameter, but adds 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?

The description opens with a precise statement of what the tool does — understand the REGULATORY POSITION of a filing — and immediately distinguishes it from siblings by naming exactly what it is not ('NOT to understand what the filing does or how it rates'). The verb+resource pair ('semantic search over correspondence_embeds') 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?

Explicit when-to-use ('Right tool for questions about the state's dialogue'), when-not-to-use ('Wrong tool for content questions'), and concrete alternatives — search_summary_embeds, search_actuarial_embeds, search_filing_embeds, list_email_workload, get_filing_correspondence — each with the condition that selects it. Even provides combination guidance for pairing with get_filing_correspondence for end-to-end thread reads.

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 readOnly and idempotent hints. The description adds valuable behavioral context (e.g., cost breakdown, aggregate behavior when serff is set, no LLM involvement) 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 lengthy but well-structured with sections and bullet points. It front-loads core concepts and every sentence adds value, though slight brevity could improve conciseness.

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?

Completely covers use cases, alternatives, and behavioral traits. Includes corpus statistics, explains return format, and addresses edge cases like scoping with serff. No output schema but description compensates adequately.

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

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

Schema coverage is 100% so parameters are well-documented. The description adds extra context for key parameters like aggregate and serff, enhancing understanding 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 it is a 'pure vector search over per-chunk full-document embeddings' for granular semantic search, and explicitly distinguishes it from sibling tools like search_summary_embeds and search_filings.

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 explicit 'Right surface for' and 'Wrong surface for' sections, detailing when to use this tool vs. alternatives, and includes guidance on aggregate and serff parameters.

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 annotations (readOnlyHint, idempotentHint), the description adds: all filters AND together, default/capped limit, descending order, pagination via offset, total count independent of limit/offset, validation of predecessor_prefix with error response, and that only fully read/classified filings are returned. This gives comprehensive behavioral 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 well-structured with clear sections: purpose, behavior, common patterns, special parameter details, and data readiness. Each sentence adds value, and it is front-loaded with the core purpose. Despite length, it is efficient and not verbose.

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 13 parameters, no output schema, and 16 siblings, the description is complete: it explains input, behavior, pagination, error handling, common patterns, and the return shape (lite row with specific fields). It also clarifies that partial filings are hidden. No gaps for a search tool.

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

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

Schema coverage is 100%, but the description adds significant meaning: common patterns for each parameter, mutual exclusivity of year vs year_from/to, wildcard matching behavior for filing_type and product_type, and precise explanation of predecessor_prefix. This goes well beyond the schema alone.

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 searches the SERFF filings corpus by various criteria and returns a lite row shape, explicitly distinguishing from get_filing_summary for substance. The verb 'Search' and resource 'SERFF filings corpus' are specific, and it differentiates from siblings as a search/discovery 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 provides explicit guidance: follow up with get_filing_summary for details, prefer structured fields over free-text, and includes common patterns like 'All California auto filings from 2024'. It tells when to use this tool and when to narrow or paginate, but does not explicitly contrast all siblings; however, the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false. The description adds key behavioral details: it's a pure vector search with bounded cost, no LLM planning, defaults topK=10 with max 50, and clarifies behavior when filters narrow candidate set (no silent fallback). This provides substantial context beyond 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 well-structured with sections, bullet points, and clear headings, front-loading the core purpose. While it is somewhat lengthy, every sentence adds valuable information for a tool with 13 parameters and multiple use cases. Minor verbosity prevents a 5.

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 (13 parameters, no output schema), the description is remarkably complete. It specifies return fields (serff, similarity, excerpt, meta), excerpt length (800 chars), filtering behavior, combination strategies, and caveats like corpus coverage. No obvious gaps remain.

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?

All 13 parameters are fully described in the schema, but the description adds significant meaning beyond the schema. For example, it advises short specific queries for best matches, explains topK behavior with filters, notes that state corpus currently covers CA only, and includes substring match examples for product_type. This greatly aids correct parameter usage.

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 'Pure vector search over per-filing extraction-summary embeddings' and explains the return of semantically closest filings with metadata. It explicitly distinguishes from sibling tools like search_actuarial_embeds and search_filings, making the purpose 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 provides explicit when-to-use (content questions about what filing is about) and when-not-to-use (actuarial-shape, concrete filters, SERFF already in hand) guidelines. It also offers combination strategies with other tools, such as first using search_filings for candidate sets.

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