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, non-destructive and closed-world, and the closing sentence confirms read-only. Beyond that, the description discloses non-obvious behavior the annotations cannot: default ordering by filing count descending with ticker tie-break, alphabetical sorting in tickers view, and which view is paged. It does not discuss rate limits or the cost of the tickers view, but the behavioral picture is notably richer than the annotations alone.

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 view semantics, then the ticker filter, then exclusions and safety — a sensible order with no filler sentences. Slightly dense and the '0700' example duplicates the schema's own example, which is the only real 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?

An output schema exists, so return values need not be explained, and the description covers the remaining agent-facing questions: which view to pick, how results are ordered, how paging behaves, and which sibling to use instead. Nothing needed to call this 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 meaning: the view enum's return shape and sort order (count-descending for companies, alphabetical for tickers) and paging scope, plus the case-insensitive substring semantics of ticker with a concrete example. It goes beyond restating the schema even though the ticker example is duplicated from 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?

States a specific verb and resource ('list companies... that have filings') and immediately distinguishes the two modes of operation (view="companies" vs view="tickers"). It also names the sibling tools it is not, so an agent can separate it from search_filings and get_statistics 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 carves out the two wrong-use cases: 'Not for a company's filings (use search_filings) or for aggregate counts (use get_statistics with group_by="company_ticker")'. This is textbook when-to-use/when-not-to-use with named 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/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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real context: it discloses the return contents (ids, license, optional extra, configured/available status, per-sink capabilities, read-serving sink) and explicitly states 'Reads no filings,' which is a meaningful scope constraint. It stops short of noting any cost or rate-limit behavior, so not 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 trigger condition, and every sentence is on-topic. There is mild redundancy: get_server_info is invoked twice and the equivalence 'get_server_info with include="sinks" returns this same payload' restates the routing already implied, which adds length without new decision 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?

Despite a single optional parameter and an existing output schema, the description stays complete: trigger, alternatives, narrowing path, and return-contents summary are all present. Nothing an agent needs to call it correctly is missing, and no return-value documentation is required given 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 coverage is 100% and the schema already explains sink_id (narrow to one configured sink id, empty returns all). The description reinforces the semantics contextually ('pass sink_id to inspect one sink without the full list'), tying the parameter to an intent rather than just a type, which is a modest but genuine addition over the baseline 3.

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 (list configured sinks/databases and their capabilities) and explicitly differentiates itself from the closest sibling, get_server_info, including the exact argument variant that would substitute for it. An agent can select this over siblings 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 when-to-use ('user asks which databases are configured or their capabilities') and when-not-to-use (use get_server_info with include='config' for the raw DATABASE_TARGET string, or include='sinks' for the same payload). It also names the sink_id path for narrowing to a single sink, covering all three invocation modes.

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.