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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it reads no filings, defaults to returning all schema sections, and can save tokens when narrowed with section.

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

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

The description is compact and front-loaded with the key guidance. Each sentence earns its place: when to use, what to use instead, how to narrow output, and what the default returns. No filler or redundancy.

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

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

For a read-only schema-introspection tool with one optional parameter and an output schema, this description is complete. It covers use timing, sibling routing, parameter behavior, and side-effect profile without needing to document return values.

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 parameter is already fully documented. The description adds value by explaining the token-saving rationale for passing section and enumerating what the default return includes, going beyond the schema's enum definition.

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 purpose: learn the canonical fields before filtering or interpreting results. It names the resource (the schema) and clearly distinguishes the tool from query siblings like search_filings and search_documents.

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

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

It explicitly says when to use the tool (before filtering/interpreting results) and points to alternatives for querying once field names are known. This gives an agent a concrete decision rule rather than leaving usage 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 declare readOnly, idempotent, non-destructive, closed-world, so repeating 'Read-only' adds nothing. However the description discloses two non-obvious behaviors beyond the annotations: rows are newest-first, and totals aggregate the full filtered range regardless of limit. That is real behavioral value.

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, then alternatives, then parameter behavior, then ordering and read-only note. Every sentence earns its place, though the trailing 'Read-only' is redundant with the annotations and the multi-clause structure is slightly dense.

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

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

An output schema exists, so return format need not be explained. With purpose, alternatives, filtering semantics, ordering, and aggregation behavior all covered, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: date_from/date_to filter by chunk month (not filing or ingestion date), and limit caps rows while totals stay unaffected by it. That clarification materially changes how limit is used.

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

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

States a specific verb and resource — reporting scrape coverage per monthly chunk, with totals — and explicitly contrasts itself with get_statistics and verify_sinks in the sibling list. An agent can distinguish it from every listed sibling without opening a 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?

Names two alternatives with the exact condition that selects each: get_statistics for filing counts grouped by a dimension, verify_sinks for cross-sink comparison. Explicit routing guidance, not merely implied 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?

Beyond the readOnlyHint annotation, the description adds a precise paging contract: document_text is a window of max_text_chars from text_offset, text_truncated signals another page, and next_text_offset is the continuation point. It also discloses that tables are only included when include_tables is true, which is valuable 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 concise and well-structured: core purpose first, then return fields, paging behavior, table inclusion, and the source of IDs. Every sentence contributes operational guidance with no filler or redundancy.

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

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

With a full input schema, rich annotations, and an output schema present, the description covers the remaining operational essentials: paging, table inclusion, and how to get the filing ID. An agent has everything needed to invoke the tool correctly and process paginated 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?

The schema covers all five parameters with descriptions, so the baseline is solid. The description adds extra relational meaning by explaining how text_offset, max_text_chars, and next_text_offset work together for pagingapper. It does not add much on filing_id, but the schema already covers that sufficiently.

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: 'read one filing's metadata and extracted document content.' It clearly identifies this as a single-filing accessor and distinguishes it from search-oriented siblings by directing agents to obtain IDs from 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?

It states the intended use case ('Use this to read one filing's...') and the prerequisite workflow of obtaining IDs from search_filings. However, it does not explicitly name alternatives like get_filings or describe when not to use them, so the guidance is clear but not fully exclusionary.

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

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

Annotations already declare readOnly=true, idempotent=true and destructive=false, so safety is covered. The description nonetheless adds real behavior: missing ids surfaced in ``not_found``, text extraction off by default, and the text window being bounded. It stops short of describing pagination or ordering, so not a full 5.

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

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

Front-loads the batch purpose and the sibling contrast, then groups parameter relationships compactly. Minor redundancy with schema defaults (text off by default is stated twice) keeps it just shy of 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?

With an output schema present, return values need no explanation, yet the description still flags the ``not_found`` field and the default-off text behavior. Combined with the id-count limit and source constraint, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the 3 baseline would apply on defaults alone. The description goes further by spelling out inter-parameter relationships: max_text_chars is per filing and only effective when include_text is true, and include_tables is independent of the text window.

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 precise verb and resource ('read several filings in one call, up to 50 ids') and explicitly contrasts with the sibling get_filing for single-filing reads. An agent can distinguish it from get_filing and search_filings without opening any 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?

Names the alternative ('Use get_filing instead to read a single filing') with the exact condition that selects it, and states the source constraint for ids ('must come from search_filings'). Both the routing decision and the prerequisite are explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description nonetheless adds real behavioral context ('Returns server metadata only; it reads no filings') and clarifies that the call can fold in other payloads in a single request. The closing 'This tool is read-only' is redundant with readOnlyHint, which keeps it from a 5.

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

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

Front-loaded with the primary instruction and organized around the include values. Mild redundancy between 'Returns server metadata only; it reads no filings' and the trailing 'This tool is read-only', plus a slightly awkward em-dash sentence, costs a 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?

With an output schema present, return values need not be explained; the description covers purpose, routing, and the semantics of the single parameter. For a zero-required-parameter read tool, 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% and the enum is self-describing, but the description adds meaning beyond the schema: it explains the consequence of each value (folds in the list_sinks payload or the configuration payload) and names the defaults, which the schema alone does not fully convey.

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 action (learn server version, configured sinks, read sink) with a concrete priming instruction ('Use this first'). It also distinguishes itself from list_sinks, which an agent can act on without opening any 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?

Explicit when-to-use ('use this first'), explicit alternative routing ('call list_sinks directly when sinks are the only thing you need'), and explicit per-value intent for include=config vs include=sinks. Nothing is left 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 declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: filters combine with AND semantics, group_by="sink" only honours a subset of filters and returns relational-sink totals, top_n/min_count cap display buckets while total still counts every match, and buckets are sorted count-descending. This is exactly the extra context the annotations cannot carry.

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, then siblings, then semantics — a logical order. It is dense and long, but nearly every clause carries a distinct behavioral fact (filter interaction, sink caveat, bucket vs total), so little 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?

For a 13-parameter read-only aggregation tool with 100% schema coverage and an output schema present, the description covers the interaction rules and edge cases an agent needs (AND filters, sink-mode caveats, total vs buckets). Return-format explanation is correctly left to the output schema.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds real meaning on top: the AND semantics across the 13 filters, the filter-subset restriction under group_by="sink", and the distinction that min_count/top_n never affect the reported total. It does not document every individual filter, which the schema already does.

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

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

States a specific verb+resource: counting filings grouped by one dimension or per sink. It also explicitly contrasts itself with its two closest siblings (get_coverage, verify_sinks), so an agent can route without opening another 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?

Gives explicit when-to-use criteria ('grouped breakdown of one population') and names the alternatives with their distinguishing conditions: get_coverage = scrape coverage by month, verify_sinks = comparison across sinks. Nothing is left 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the 'read-only' sentence is partly redundant, but the description goes beyond them by disclosing ordering semantics (count descending, ticker ties ascending), paging behavior, and case-insensitive substring matching. Return shape details are minimal but the output schema covers that.

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 tool's purpose, then proceeds parameter-by-parameter with zero filler. Every sentence (modes, ordering, ticker matching, alternative tool, read-only flag) carries distinct 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?

With an output schema present, the description need not explain return values, and it still covers both view modes, ordering, paging, and filtering comprehensively. An agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description adds ordering and default-view behavior beyond the schema, but largely restates the view and ticker semantics, so it sits at the baseline expected when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('list companies... that have filings') and precisely distinguishes its two output modes, view='companies' versus view='tickers', including their respective orderings. It also implicitly separates itself from search_filings, which handles the filings themselves.

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

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

It gives clear routing guidance by naming search_filings for retrieving a company's filings, which is the likely competing tool. However, it never states exclusions or prerequisites (e.g. what a company must have to appear), so this is good context without full when/when-not coverage.

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/destructiveHint, so the safety profile is covered. The description adds real value beyond them: results are paged via limit/offset and 'stay empty until graph linking has been run' — a non-obvious precondition an agent would otherwise misread as a bug.

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

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

Front-loaded with the purpose, then alternatives, then semantics and caveats. Every sentence carries information, though the parenthetical list_companies reference and repeated ticker format make it slightly longer than strictly necessary.

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

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

An output schema exists so return shapes need no explanation, and the description still covers the paging model, the empty-until-linked precondition, the kind semantics, ticker validation, and read-only status. 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. The description goes beyond the schema by explaining what kind='referenced_by' vs 'owned' mean in graph terms (title-mention cross-references vs the company's own filings) and reiterates the ticker format with a discovery path, giving the enum semantics real operational 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 a specific verb and resource ('explore the graph edges between companies and filings') and immediately names the sibling tools (search_filings) it must not be confused with. An agent can distinguish it from get_filings/search_filings without opening any 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?

Explicitly routes the agent: search_filings(ticker=...) for a company's own filings vs search_filings(referenced_ticker=...) for mentions, and explains that this tool reads canonical edge tables. It also names list_companies(view='tickers') as the discovery path for valid ticker values.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful non-annotation context: 'Reads no filings' and that get_server_info with include="sinks" returns the identical payload, which helps an agent avoid a redundant call.

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

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

Front-loaded with the trigger condition, then alternatives, then parameters. Slightly redundant in mentioning get_server_info twice and re-explaining the same payload, but no sentence is truly 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?

For a read-only list tool with a complete schema and an output schema, the description covers triggers, alternatives, parameter behavior, and return shape. Nothing needed to invoke 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% and the single sink_id parameter is fully documented in the schema ('Narrow to a single sink id, e.g. postgres; empty returns all'). The description's 'Pass sink_id to inspect one sink without the full list' largely restates that, adding only the side effect of shrinking the payload, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('which databases are configured or their capabilities') and explicitly names what it is not (get_server_info for the raw DATABASE_TARGET string). An agent can distinguish this from sibling get_server_info without opening either schema.

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

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

It gives explicit when-to-use guidance, names the alternative tool with the exact parameter (get_server_info include="config"/"sinks"), and states the condition for passing sink_id versus listing everything. Nothing is left 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?

The description adds substantial behavioral context beyond the annotations: case-insensitive matching, snippet availability depending on sink support, AND-filter semantics, and the dependency on documents being processed before results appear. It also restates the read-only nature consistently 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 well-organized and front-loaded with the core use case, followed by routing guidance and behavioral notes. Every sentence adds value without unnecessary repetition or filler.

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

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

For a tool with 100% schema coverage, an output schema, and strong annotations, the description covers the remaining contextual gaps: when to use it, how filters behave, and what prerequisites affect results. Nothing essential for correct invocation 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. The description adds meaning beyond the schema for key parameters: text_query's matching behavior, document_type's allowed values, source's example, and the AND combination of filters. It doesn't discuss every parameter, but the schema already covers those individually.

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: full-text search over extracted document text, matching text_query inside document_text. It clearly distinguishes itself from the sibling search_filings by contrasting full-text search with metadata-only 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?

Explicitly names the alternative: 'Use search_filings instead to filter by metadata without a text query.' It also clarifies when search_documents applies and notes that all filters combine with AND semantics, giving an agent a clear decision rule.

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 destructiveHint=false, so the safety profile is covered structurally. The description adds genuine value by disclosing return behavior ('Returns paged filing rows (no document text)') and explaining the 'unprocessed' status edge case — details an agent could not infer from annotations or schema.

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?

Purpose and routing are front-loaded in the first two sentences, and the filter-semantics block is dense but every sentence earns its place for a 15-parameter, all-optional tool. It is a long single paragraph and could benefit from light grouping, but there is no fluff 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?

For a complex search tool with 15 optional parameters, the description covers everything needed for correct invocation: purpose, sibling routing, filter combinability, value domains, date semantics, sort options, return behavior, and read-only confirmation. Output schema covers return fields and annotations cover safety, so no critical gap remains.

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

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

With 100% schema description coverage, baseline is 3, but the description adds meaning above that: it generalizes comma-separation across filters with a concrete example (filing_type="Annual Report,Dividend"), clarifies date formats as YYYY-MM-DD inclusive, enumerates order_by values with the default, and defines document_status's special 'unprocessed' value.

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 plus resource and scope: 'find filings by ticker, type, status, date range, or title text.' It differentiates from siblings by naming what it is not — search_documents (full-text over extracted text) and get_filing/get_filings (by known ids) — so an agent can route correctly without opening any 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?

Gives explicit routing: 'Prefer search_documents for full-text search over extracted text, and get_filing or get_filings to read filings whose ids you already have.' It also states that filters are optional and combinable, covering both when to use and when not to use this tool.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial behavioral detail: it explains the return shape (bounded samples of missing/extra/mismatched ids, per-sink counts and spread, parity OK when spread is zero) and clarifies that sample_size bounds examples rather than the comparison and is ignored in counts mode. It also notes the tool is read-only, reinforcing annotations without contradicting them.

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

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

The description is front-loaded with purpose, then mode details, alternatives, and parameter relationships, with no filler. It is a bit dense and includes one redundant sentence ("This tool is read-only"), but the length is justified by the tool's comparison modes and cross-parameter constraints.

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, the 100% schema coverage, annotations, and an existing output schema, the description covers everything an agent needs: when to use each mode, what the tool returns, parameter constraints, and explicit alternatives. No critical gap remains 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 coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter semantics beyond the schema: sinks must list two or more comparable sink ids from list_sinks, empty compares every comparable pair, and sample_size bounds examples per problem bucket rather than the comparison itself and is ignored by mode="counts". These relationships are not captured in the input 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?

States a specific verb and resource: check that configured sinks agree on their filings, and clarifies the two modes (hashes vs counts). It also names sibling tools get_statistics and get_coverage for adjacent tasks, so an agent can distinguish this tool's purpose without opening 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?

Gives explicit when-to-use guidance for each mode and names alternatives: use get_statistics for per-sink totals or grouped breakdowns, and get_coverage for monthly scrape coverage. It also states that sinks must list two or more comparable sink ids from list_sinks, and that empty compares every comparable pair.

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