Edgar

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context: the default model is free, Anthropic calls require a BYO key with direct cost to the user, and the response structure includes per-model score, confidence, signals, and raw_response. This complements the annotations without contradiction.

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

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

The description is front-loaded with the core purpose and result, then details the default model and optional Anthropic integration, and ends with use cases. It is efficient and avoids fluff, though it could be slightly tighter. Each sentence earns its place, so it merits a 4.

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, idempotent tool with no output schema, the description adequately explains the return format (per-model structure plus combined view) and covers all parameters via the schema. It also provides usage context. No critical information is missing for an agent to call it correctly, though error handling and rate limits are not addressed.

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 in the input schema. The description adds marginal value by reiterating the default model and the _apiKey's purpose, but it does not introduce new parameter semantics beyond what the schema provides. 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 states a specific verb ('Probe') and resource (LLMs), and clearly defines the outcome: scoring visibility from 0-100 per model. It goes beyond the title by specifying the default model and the option to probe Anthropic, and lists concrete use cases, making the purpose unmistakable even among many sibling tools.

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

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

The description provides clear contexts for use ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which implicitly tells when to invoke it. However, it does not explicitly name alternatives or state when not to use it, so it falls short of the highest level of 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 declare readOnly/idempotent/openWorld, and the description adds substantial context beyond them: which archives are queried, that diffing is on readable text not markup, the max_gap_days fallback behavior, and the exact no_capture and changed:false outcomes with their reasons. This is precisely the behavioral detail an agent needs to interpret results.

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

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

Front-loaded with the core question, then moves through mechanics, edge cases, and use cases in a logical order. Dense but every sentence contributes; slightly long but not padded.

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 carries the return-shape burden and does so fully: diff segments, similarity score, both capture timestamps with gaps, and status values for the no-capture case. An agent knows what it will get 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 coverage is 100%, so baseline is 3; the description adds meaning by explaining that dates resolve to the nearest capture within max_gap_days and reporting capture-timestamp gaps. It complements rather than repeats the schema field 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?

Opens with a specific question form and names the exact resource and operation: resolving archived captures and returning a text-level diff. It clearly distinguishes itself from sibling archive_evidence and resolution_diff by specifying text-level diffing and multi-archive resolution.

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 typical uses (privacy policy, ToS, pricing changes, whether a statement was on a page) and states the semantic boundary that markup diffs are out of scope. It does not name sibling tools or say when to prefer archive_evidence instead, so it falls short of a full 5.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses the fallback status semantics, that a distant capture is never silently substituted, that every archive's outcome appears in sources[] with upstream status, that all-archive failure returns a distinct error, and that results are cached by immutable capture id with served_from indicating cache vs upstream.

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 user-facing question and the core behavior, and nearly every clause carries new information (sources, errors, caching, gap). It is dense and long for a single paragraph, which costs a point, but there is little 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 no output schema, the description carries the return-shape burden and does so: text body, capture timestamp, archived-copy link, gap message, status values, sources[], served_from, and error codes. An agent has everything needed to call it and interpret the response.

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, and the description adds real meaning for max_gap_days by explaining its purpose (a capture beyond the gap is refused rather than passed off as the requested date) and by describing the gap value returned. max_chars is left entirely to the schema, so it falls short of a 5.

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 ('Finds the archived capture of a URL nearest that date... reads it, and returns the readable text') and names the three upstream sources. The opening question and the explicit contrast with archive_compare let an agent distinguish it from siblings 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?

Explicitly routes the agent elsewhere ('Use archive_compare to see what changed between two dates') and defines the boundary condition for a non-answer (no capture within max_gap_days yields status 'no_capture'). It also distinguishes the failure modes an agent might otherwise conflate, no_capture vs error 'archives_unavailable'.

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, openWorld, non-destructive), and the description adds substantial context beyond them: automatic argument filling, return of pipeworx:// citation URIs, and the pack-fallback contract where unknown slugs are named in _meta.pack_scope.ignored and never yield an empty answer. That is genuinely useful routing behavior disclosure.

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 core purpose and the PREFER OVER WEB SEARCH directive, but the passage is long and carries marketing-tone lines ('START HERE', 'works on every tier') that dilute signal. Every sentence is relevant, but some could be tightened.

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

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

For a no-output-schema router, the description covers inputs (natural-language question, optional packs), routing behavior, and return shape (structured answer with stable citation URIs). Nothing an agent needs 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 description coverage is 100%, so the baseline is 3; the aliases (q, ask, text, input, prompt, message, query) are self-documented in the schema. The description adds routing meaning for the packs parameter ('restrict routing to these sources'), though it largely restates the schema's own pack detail.

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 (routes a natural-language question to the right tool) and scope (6,919 tools across 1820 sources), then names the exact class of questions it serves with concrete examples. An agent can distinguish it from ask_pipeworx_grounded and deep_research 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 says when to choose this over alternatives ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and names the two step-up siblings with the exact conditions that select them (hallucination-resistant single answer vs. broad multi-source fan-out). No inference required.

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 (readOnly, idempotent, openWorld, non-destructive) already carry the safety profile, and the description adds real context beyond them: it is compared against the stable router for merge decisions, candidate improvements are enabled live, and 'Falls back to nothing — this IS a full working router' preempts an agent assuming degradation. It does not discuss latency, cost, or result-quality tradeoffs of the experimental path.

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 identity claim and the tool count, then usage, then the no-fallback reassurance. It is mildly redundant — 'identical ... router' and 'currently matches ask_pipeworx exactly' restate the same relationship, and the retirement date is more provenance than guidance — but nothing is seriously bloated.

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

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

The tool is a complex router with no output schema, and the definition covers routing scope, fallback behavior, comparison protocol, and the packs semantics by reference. The one gap is return values: 'same response shape' is asserted but never described, leaving the response contract to be inferred from the sibling 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 all nine parameters (including the alias cluster and the packs filter) are already documented in the schema, which sets the baseline at 3. The description adds only 'same arguments', which conveys no argument-level detail 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?

States a specific verb+resource (a routing/answering tool) and explicitly positions itself against the sibling ask_pipeworx: 'identical universal router (same 6,919 tools, same arguments, same response shape)'. An agent can distinguish it from ask_pipeworx, ask_pipeworx_grounded and deep_research 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 the selection condition explicitly: 'Use it exactly like ask_pipeworx when you want the newest routing', and names the stable router as the comparison baseline. It stops short of stating when NOT to pick it — notably, the admission that it currently matches ask_pipeworx exactly undercuts the reason to choose it, and no exclusion guidance is offered for the already-selected-tool scenario.

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

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

Annotations only declare the safe read-only profile, but the description adds substantial context beyond them: the exact success payload shape, the five named refusal reasons, and the extra-LLM-call cost. This is behavior an agent needs to choose and interpret 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?

Dense but front-loaded, starting with the core differentiator and ending with the cost-based routing rule. The return/refusal enumeration is somewhat long but earns its place given there is no output schema.

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 and refusal taxonomy itself, plus usage conditions and cost. Nothing an agent needs to invoke or interpret the tool 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 aliases and prefer_tool semantics are fully documented in the schema. The description adds routing context (arguments are filled from the question) but no syntax or format detail beyond it, so 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?

States a specific verb (extract/answer) and resource (data fetched via routing), and explicitly distinguishes itself from the sibling ask_pipeworx by explaining the grounded extraction step and refusal behavior. An agent can tell the two apart 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?

Gives explicit when-to-use (quoted, cited, or acted-on answers where facts must not be invented, with concrete domains) and when-not (casual lookups where ask_pipeworx is preferred). Names the alternative and the cost tradeoff that selects 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 cover only the safety profile (readOnly/openWorld/idempotent/non-destructive), and the description adds far beyond that: BLOCKING short-circuit statuses (low_confidence_match, market_closed_or_inactive, market_expired_or_resolved), the resolver contract with match confidence scores, GDELT 429 fallback fields, illiquid_wide_spread flagging, and cancellation-rule settlement parsing. These are exactly the operational traits an agent needs to avoid misusing results (e.g. sizing on phantom matches).

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 is front-loaded, but the body is an unusually dense wall of ALL-CAPS headers and enumerated classifier/fan-out/status lists. Much of this is useful given the absent output schema, yet the density and length exceed what most agents will parse, so structure is adequate but not economical.

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 carries the full return-shape burden and does so: result.market fields, result.analysis fields (model_probability/edge_pp/kelly_fraction_half), result.evidence keying, resolver contract fields, parent_event partition fields, and news fallback metadata are all documented. An agent can interpret responses without guessing.

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 genuine meaning: it explains WHY to prefer an undated slug (dated slugs stop resolving once settled because Polymarket de-indexes resolved markets) and ties fuzzy matches to the suggestions[]/market_match_alternatives[] re-query hints. The depth and include_raw semantics largely restate the schema, so it is not a full 5.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call') and enumerates the full pipeline (resolve → classify → fan out → evidence packet + model comparison). Sibling Polymarket tools (edges, arbitrage, fill_risk, kalshi_spread) are implicitly distinguished by the 'should I bet on X / what does the data say / is there edge' trigger framing, which reads as research rather than scanning or spread-monitoring.

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?

Trigger phrases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') give clear usage context, and the safety section explains when the tool effectively won't produce analyzable output. However, it never names an alternative sibling or states when NOT to use this tool (e.g. bulk edge-scanning belongs to polymarket_edges/arbitrage), so routing vs. alternatives 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 cover readOnly/idempotent/openWorld/non-destructive, and the description adds substantial context on top: cost profile ('cheap', one small model call), the verification rule that 'found' requires the quote to be an independently verified verbatim substring, the fetch fallback, and the no-call degenerate behavior. This goes well beyond what the structured fields disclose.

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 purpose, then the return contract, then parameter routing. Dense but each sentence carries information (cost, evidence semantics, fallback, degenerate case). Slightly long, but no 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?

With no output schema, the description supplies the return shape ({label, applies, evidence_url, quote, status}) and the status semantics, plus cost and fallback behavior. An agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: text is the cheapest path that skips fetching, domain is used ONLY when text is absent, and text+domain both missing yields not_established with no model call. This clarifies the interaction between parameters that the schema alone doesn't spell out.

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 ('decide which labels apply' for a given company against candidate labels) and frames the GTM/AI use case. It explicitly contrasts itself with research_row as the cheap, single-model-call alternative, so an agent can separate it from siblings on intent alone.

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 concrete routing conditions for the parameters: pass text directly as the cheapest path, use entity.domain to fetch the homepage as a fallback, and the degenerate case of neither. It also references research_row's evidence contract implicitly. It does not explicitly state when to prefer research_row or other research siblings over this one, so not a full 5.

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

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

Annotations only declare the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false). The description goes far beyond that, disclosing the never-substitute-latest guarantee, never-return-0, currency non-conversion, the YTD-minus-YTD derivation with `reported:false` and named derivation paths, per-share/balance-sheet non-derivation, and the full set of named non-answer statuses. This is exceptional behavioral disclosure.

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 key purpose and the 'prefer over' routing are front-loaded, and every sentence carries substantive information for a high-complexity tool. It is dense and long, but the density is largely earned by the derivation and status semantics; minor trimming is possible but nothing is 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?

There is no output schema, so the description carries the full burden — and it does: it enumerates return fields (us-gaap concept, measure, accession, sec.gov link, restatement trail, contract/derivation version), the derivation marker, and all named status outcomes. Nothing an agent needs to call or interpret the result 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. The description nevertheless adds conceptual meaning beyond the schema: the NetIncomeLoss-vs-ProfitLoss concept distinction, the dei cover-page basis and cover-date period for shares_outstanding, and mixed units (shares vs USD/shares). Some overlap with the schema's own attribute descriptions keeps it from a 5.

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+resource+scope: typed, deterministic financial facts for a US public company for an explicitly named reporting period, with concrete examples ('Apple revenue for fiscal 2023'). It explicitly differentiates itself from entity_profile and get_company_financials, so an agent can select it 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 alternatives (entity_profile / get_company_financials) and the exact condition that selects this tool ('whenever the period matters'), then explains the failure mode of the alternatives (returning FY2025 for an FY2019 question, conflating discrete quarters with YTD). This is textbook when-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 declare read-only/idempotent/open-world/non-destructive, but the description adds substantial behavior beyond them: it refuses to guess and returns match_status 'ambiguous' with both candidates, exposes searched[] with per-register as-of dates and errors (unreachable register ≠ zero rows), and explains related[] collapsing. This is exactly the extra context the annotation bar rewards.

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 core action and return value, then progressively details registers, ambiguity behavior, and exclusions in well-signposted blocks. It is dense and slightly repetitive (the register list and 'refuses to guess' theme recur), but length is largely justified by the tool's complexity.

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

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

With no output schema, the description carries the burden and discharges it: it describes return fields (searched[], related[], match_status), error semantics, scope (not a people search), and register coverage. An agent has everything needed to call and interpret this complex 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%, so the baseline is 3, but the description adds decision-relevant meaning: it explains that a short name is often ambiguous and that passing country is 'frequently the difference between an answer and ambiguous', reinforcing schema semantics with usage guidance. It largely echoes the schema's name/limit detail, so it does not fully exceed the baseline.

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 ('Search the NATIONAL BUSINESS REGISTERS by company name') and the precise return artifact ('get the register's own id back — a Companies House number, ...'), with concrete examples of the identifier types. It also carves out its sibling explicitly ('For US public companies prefer resolve_entity'), so an agent can distinguish it from the nearest alternative 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?

Explicit when-to-use ('when you want the OFFICIAL REGISTERED ENTITY and the country is not the US, or when you do not know which country it is'), explicit when-not (US public companies → resolve_entity, natural persons excluded), and explicit advice on passing country to avoid ambiguity. Alternatives and conditions are named, not inferred.

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, openWorld, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond those annotations, including data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sorting by primary metric, and citation URI returns. No contradictions found.

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

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

The description is information-dense and front-loaded with trigger phrases and the main instruction. While it is relatively long, the additional details about data provenance, sorting behavior, and fiscal-year handling earn their place in helping an agent invoke the tool correctly.

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 input constraints (via schema), data sources, return content, sorting, and citation URIs, which is especially valuable since no output schema exists. Minor gaps remain around units, currency, or clear error cases, but overall the agent has enough context to use the tool properly.

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 meaning beyond the schema by clarifying what each 'type' maps to (company financials vs. drug adverse-event/trial data) and by explaining values as tickers/CIKs or drug names. It also enriches the 'type' enum with concrete business details.

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

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

The description clearly identifies a specific operation (side-by-side comparison) and resource (2–5 companies or drugs in one parallel call). It also distinguishes itself from sequential single-pack lookups, making its purpose unambiguous relative to sibling tools.

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

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

The description explicitly says to prefer this tool over sequential single-pack lookups when comparing entities aid provides natural-language trigger phrases. It lacks explicit mention of exact alternative sibling tools or clear 'when not to use' scenarios, but the intended usage context is very clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: account/tier gating, parallel routing, gaps[] never invented, hop and citation_uri semantics, contradiction passes, latency expectations (15-60s, up to ~90s), and semantic excerpting rather than head-truncation.

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 blocking prerequisite (account required) and the fallback, which is the right ordering. The prose is dense but long; nearly every clause carries a distinct constraint (tier gating, latency, citation fetchability), though it could be tightened by grouping the citation/gap 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?

No output schema exists, and the description compensates by describing the return shape precisely: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, hop field, gaps[], and contradictions[]. Nothing an agent needs to decide and call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description additionally explains the account dependency for depth:'thorough' and characterizes the depth tiers by hop behavior, and the alias parameters are documented in the schema. It adds real meaning over the enum list but does not add syntax beyond that.

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 (grounded multi-source research), scope (1,820 structured sources, 6,919 tools in parallel), and explicitly negates the alternative interpretation ('this is NOT open-web search'). It is instantly distinguishable from ask_pipeworx and from open-web search tools.

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

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

Gives explicit when-to-use (broad/multi-part questions over structured data, with two concrete examples), when-not (single lookup, breaking/colloquial news), and the named alternative ask_pipeworx for each case. Also states the account prerequisite and which tier unlocks thorough.

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; the description adds substantial value by disclosing the exact return shape: top-N relevant tools with names, descriptions, full input schemas and curated examples, and that results are ready to call without a second schema lookup. This is especially useful because no output schema is provided.

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

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

The description is front-loaded with the core purpose, followed by use cases, return value, and a clear first-step instruction. Each sentence earns its place, and the domain list is dense but directly relevant.

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 discovery tool with straightforward parameters, high schema coverage, and no output schema, the description fully compensates: it explains what the tool does, when to use it, and exactly what the response contains. Nothing materially needed by an agent 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 schema already documents query, all aliases, and limit defaults/max. The description only restates that the input is a natural-language description of a data/task, adding no parameter-level meaning 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 first sentence names a specific action and resource: 'Find tools by describing the data or task.' It also lists concrete domains and frames the tool as a discovery/meta tool, which distinguishes it from the many operational sibling tools and clarifies it is not itself a domain-specific search.

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

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

The description explicitly says when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and instructs to call it FIRST when many tools are available. It does not name specific alternative tools or give explicit exclusions, though 'not just one answer' hints at when a direct tool is more appropriate.

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 destructiveHint=false, and the description adds substantial behavioral context beyond that: results sorted with listed peers first, delisted/defunct filers included, unlisted registrants returned with ticker:null rather than dropped, self-exclusion default, form_type='10-K' as an active-reporter filter, and upstream unreliability without it. This is rich, honest behavioral disclosure.

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 dense with useful, non-redundant information and is front-loaded with purpose and usage guidance. It is longer than ideal and uses emphatic capitalization somewhat heavily, but each sentence contributes meaningful context about behavior, sources, or caveats. Slightly sprawling but earned.

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 still covers the return shape (CIK, ticker, company_name), ordering behavior, the null-ticker case, the default form_type filter, and the reliability caveat. For a tool with 7 optional parameters and subtle behavioral quirks, nothing an agent needs 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%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the resolution flow for ticker_or_cik (look up SIC first, then find peers), the consequence of exclude_self, and why form_type should not be omitted ('unreliable upstream'). This elevates the value beyond what the structured schema alone 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 opens with a specific verb and resource: 'find every SEC filer classified under one SIC ... industry code.' It also positions itself as a peer/competitor lookup, which distinguishes it from sibling EDGAR tools like edgar_company_facts or edgar_search_filings. The scope (SIC-based, SEC filers) is unambiguous.

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

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

It explicitly tells the agent to PREFER this tool OVER WEB SEARCH for concrete intents ('who are $COMPANY's public competitors/peers', 'list companies in <industry>'). It also explains the two input modes (sic directly vs ticker_or_cik) and warns that the SIC bucket is a starting point, not a precise list. It doesn't explicitly contrast with sibling EDGAR tools, but the primary alternative (web search) is clearly handled.

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/idempotent/openWorld safety. The description adds substantial beyond-annotation context: it discloses the Q4 derivation behavior (derived:true via FY minus Q1-Q3), that SEC filers never report standalone Q4, the newest-first ordering, and the `latest` field semantics. It doesn't discuss rate limits, but the derivation and return-shape disclosures are strong value-add.

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 value proposition, but the description is long and dense, packing many overlapping points (aliases, derivation, latest semantics, examples) into a single dense paragraph. Most content earns its place, but it could be trimmed and structured more cleanly without losing meaning.

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 analysis tool with an output schema present, the description covers the key behavioral nuances an agent needs: aliasing, derivation of Q4, latest field, and period filtering. Return-format details are rightly left to the output schema. Complete enough to call 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 schema already documents all parameters thoroughly, including aliases and the fiscal_year/fiscal_period labels. The description reinforces the alias behavior (cik/ticker/ticker_or_cik, concept/metric) and explains the friendly-name vs exact-tag resolution, but the schema does the heavy lifting. Baseline 3 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?

States a specific verb+resource: retrieves authoritative historical financials from SEC XBRL filings for any US public company. It names the source, the metric resolution behavior, and clearly distinguishes itself from siblings like edgar_company_facts (raw tags) or edgar_xbrl_frames by focusing on friendly-named concepts for a single company.

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 guidance: 'Use for "what was AAPL's revenue in 2024"', 'NVDA's latest cash position', and it warns 'do not default to latest for a period question.' It distinguishes period-questions from point-in-time metrics and names when to use `latest` vs filtered values. This is unusually thorough routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it flags retired concepts as stale, notes the payload is large, and explains that latest_annual is resolved to whichever XBRL concept the filer currently reports under. This is meaningful behavioral disclosure that helps the agent anticipate output quirks.

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 dense but well-organized: it front-loads the core purpose, then covers parameter semantics, output characteristics, usage guidance, and sibling routing. Every sentence earns its place, though it is somewhat long. The structure is logical and the key differentiators are prominent.

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 (hundreds of concepts, aliases, large payload, stale concept handling), the description is remarkably complete. It covers what the tool returns, how to call it, what the aliases are, when to use it vs. alternatives, and what to expect in terms of payload size and data quality. The output schema exists, so return values need not be detailed further. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by clarifying that `cik` is the primary argument, that tickers are auto-resolved to CIKs internally, and that `ticker`/`ticker_or_cik` are aliases. This goes beyond the schema's per-parameter descriptions by explaining the relationship between the three parameters and the resolution behavior.

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 ('Returns every reported financial metric'), a specific resource ('full XBRL fundamentals dump for a US public company'), and explicitly distinguishes itself from siblings (edgar_company_concept, edgar_company_snapshot). It clearly identifies the tool's scope and differentiates it from alternatives.

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

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

The description provides explicit when-to-use guidance: 'Use when you need the complete fundamental picture vs. one metric (for one metric use edgar_company_concept)' and 'For just the headline figures plus the recent filings list, edgar_company_snapshot is the smaller one-call answer.' It also notes the typical usage pattern: 'agents typically use this once to discover available concepts then narrow to edgar_company_concept for follow-up queries.' This is explicit routing with alternatives.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. Beyond that, the description adds the authoritative/recent scope, alias flexibility, and the return fields (dates, form types, accession numbers, document links); it does not state ordering or pagination, but that is minor given the output 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?

The description is long but dense, and every sentence earns its place: purpose first, then identifier semantics, form-type filtering, return contents, use cases, and sibling routing. It is front-loaded and logically ordered with no 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 read-only listing tool with a full output schema and annotations covering safety, the description covers identification, filtering, return shape, and when to use alternatives. Nothing an agent needs to invoke it correctly is left unclear.

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: it explains that ticker_or_cik accepts either a ticker or CIK, that cik/ticker are aliases, and it labels form types ("10-K" annual report, "10-Q" quarterly, "DEF 14A" proxy, "S-1" IPO). This goes beyond the schema's terse field 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?

Opens by naming the exact deliverable: an "AUTHORITATIVE list of recent SEC filings for a specific US public company," with a concrete verb (list) and resource (SEC filings). It further distinguishes itself by naming edgar_company_concept, edgar_company_facts, and edgar_company_snapshot for different jobs.

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 conditions and examples: "Use for 'what did $TICKER recently file' or 'show me the last N proxy statements'" and routes financial metrics, full XBRL, and headline-financial-plus-filings to specific siblings. The only flaw is the reference to sec_8k_recent, which is not present in the available sibling list, making one routing instruction unactionable.

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 readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: ticker/name/CIK resolution, default substantive-form filtering, 'financials_status: unavailable' with a reason instead of an error, and stale-concept handling. It clearly discloses what the tool does and does not return 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 densely packed and front-loaded with the one-call value proposition. Every sentence earns its place: scope, defaults, alternatives, aliases, error behavior, and drill-downs are all covered without 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?

With no output schema and a complex multi-part return, the description compensates by enumerating the identity fields, filing list fields, and financial metrics, and by covering the no-XBRL edge case. It is complete enough for an agent to call the tool and interpret the result without needing to guess.

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 description adds value beyond it: explaining that `ticker_or_cik` accepts ticker, name, or CIK; that `form_type` can be a single form or 'all'; and that financial metrics are resolved to the filer's current reporting concepts. Aliases are explicitly clarified as equivalent spellings used by sibling tools.

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 uses a specific verb ('returns') and names the exact resource ('SEC picture on $TICKER'), explicitly enumerating the three outputs: identity, filings list, and XBRL figures. It distinguishes itself from the chain of edgar_ticker_to_cik -> edgar_company_filings -> edgar_company_concept and from sibling tools, making selection 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 gives explicit when-to-use framing ('ONE CALL for...'), names the manual chain it replaces, and provides concrete routing guidance for drill-downs (edgar_filing_text, edgar_company_concept, edgar_company_facts) and the cross-source alternative (entity_profile). This is the strongest possible usage 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 declare a safe, idempotent, read-only, open-world read, so the safety burden is covered. The description adds genuine behavioral context beyond that: what the return contains (name/type/size/direct https URL plus form type, filing date, index page), the ~40k-char truncation of include_primary_text, and the fallback-to-latest-any-type behavior. Not exhaustive on error cases, but well above what annotations supply.

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 purpose is front-loaded in the first sentence and every subsequent sentence carries usage or return information. It runs long and duplicates some of the schema's own examples, which is the only waste, but it stays readable and non-repetitive at the sentence level.

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 carries the return-value burden and does so fully: enumerates documents, their metadata, and the filing-level fields. Combined with the annotations and 100%-covered schema, an agent has everything needed to call this correctly across both invocation modes.

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 and the schema already documents each field. The description still adds value by pairing parameters into real call shapes (accession+ticker, ticker+form_type), noting accession works with or without dashes, and clarifying the ticker/CIK OR and omitted-form_type semantics.

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 and scope: 'AUTHORITATIVE list of the SEC filing documents inside ONE specific filing, by accession number.' It explicitly distinguishes itself from the sibling it is not (edgar_filing_text for full pageable text, edgar_company_filings via the alias note), so an agent can separate it from siblings 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?

Gives explicit when-to-use cases ('list a 10-K/10-Q/8-K's exhibits, retrieve filing contents/attachments, or fetch the text of a filing') and a clear alternative for full text ('use edgar_filing_text instead'). It also documents the auto-resolve path and even warns that omitting form_type returns routine 8-Ks/Form 4s, steering the agent to the `|` set when it wants a real report.

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 still adds substantial non-obvious behavior: `search` runs over the WHOLE document before offset/max_chars windowing, zero-match is a legitimate answer, multi-word phrases fall back to word-matching (match_mode 'words'), passages are ranked with nearby figures first, a read-side `raw_truncated` cap bounds how far offset and search can reach, and financial-total phrases return an `xbrl` value for the same accession. That is a genuinely richer behavioral profile than the annotation set provides.

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

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

The opening sentence is front-loaded and the sectioning is logical, but the body is ~600 words of dense, bold-heavy, ALL-CAPS emphasis that duplicates the schema's `search` and `form_type` descriptions almost verbatim. The inline warning about NTRA's Form 144 (fleet #2450, dated verification) is presumably internal evaluation provenance leaking into a tool description and does not earn its space in agent-facing text.

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 carries the full return-shape burden and does so: `text`, `truncated` + `next_offset` paging, `raw_truncated`, `searches[]` keyed by phrase, `xbrl`, `section_found`. It also explains the two resolution paths (accession, or ticker/cik + form_type auto-resolve) and the ticker-safety caveat. 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 description coverage is 100% and the per-property docs are already thorough, so the baseline is 3. The description nevertheless adds cross-parameter workflow meaning the individual property docs do not: how `search` and `section` compose, why `form_type` should be a `|` set rather than omitted or guessed, and how `next_offset`/`offset` page a document. It largely restates the schema's `search` entry, which keeps it short of 5.

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?

Opens with a specific verb+resource: 'AUTHORITATIVE full text of a SEC filing's primary document (10-K / 10-Q / 8-K body), HTML stripped to clean plaintext.' It explicitly carves out what it is NOT for versus siblings, naming edgar_filing_documents (exhibits) and edgar_company_concept (structured numbers). An agent can pick this over those two 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 named alternatives and the conditions that select them: use edgar_filing_documents for the document/exhibit list, edgar_company_concept for structured financials, and this tool for prose disclosures. It further routes within the tool itself — pass `search` instead of paging blind, pass `section` for one part, pass `|`-separated phrases for compound questions — with concrete example queries ('does $TICKER disclose substantial doubt', 'how many tests did $TICKER process').

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. The description adds significant behavioral context: data is ~30-60 days delayed, only US-registered funds covered, and funds like UITs are excluded. It doesn't contradict annotations—readOnly is consistent with a read-only query. The description goes beyond annotations to set expectations about data freshness and coverage limitations.

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

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

The description is longer than typical but every sentence serves a purpose: purpose, usage, examples, distinction, coverage, and exclusions. The essential info (what it does, how to use) is front-loaded, with edge cases at the end. It's not overly verbose given the complexity (fund vs manager distinction). It loses a point for being a bit longer than ideal, but it's well-organized and each sentence earns its place.

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

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

For a tool with 3 parameters and no output schema, the description is nearly complete. It explains the output will include net assets, holdings count, and top positions with name, CUSIP, value, and % of fund. It also covers common failure modes (non-US funds, UITs, CIK misuse) and provides alternatives. It doesn't specify pagination or error details, but those are less critical. Given the tool's moderate complexity, this is near-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% since both parameters have descriptions, providing a baseline of 3. The description adds value by clarifying the ticker parameter is REQUIRED (despite schema showing required: []), and warns that `ticker_or_cik` is an alias but must be a fund ticker, not a CIK. It also explains that 'limit' is a preference (1-100, default 25) implicitly. This elevates from baseline to a 4 because it clears up the ambiguity around the alias and the required nature of ticker.

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

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

The description opens with a clear verb ('Pass'), resource (US ETF/mutual fund portfolio holdings from SEC Form N-PORT), and specific scope (latest monthly portfolio with net assets, holdings count, top positions). It explicitly differentiates from edgar_institutional_holdings by naming the sibling and defining what it covers (13F managers vs. fund's own N-PORT). The phrase 'AUTHORITATIVE' adds confidence, and the list of example queries makes the purpose unmistakable.

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

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

The description gives explicit usage instructions: pass the fund's ticker (not company tickers), provides example tickers, mentions the alias `ticker_or_cik` and warns that a CIK won't resolve. It explicitly contrasts with edgar_institutional_holdings and explains the N-PORT vs 13F distinction. It also provides negative guidance: funds structured as UITs (SPY, DIA) won't work, with a suggested alternative (IVV, VOO) for S&P 500 exposure. This is exactly what the dimension asks for.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by decoding transaction codes (P, S, A, M, G, F), explaining that P is the strongest conviction signal and A is routine compensation, and describing the parsed output structure. 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?

Every sentence contributes: purpose, input identification, output structure, example use cases, signal interpretation, and alternative routing. The most important information is front-loadedaisd the 'AUTHORITATIVE' opener and the transaction-code explanations are compact and high-signal.

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 carries the burden of explaining return values, and it does so thoroughly: reporting owner, role, transaction code, shares, price, acquired/disposed, and post-transaction holdings. It also covers input alternativeschers, use cases, and the sibling for raw filings, making it complete for an agent to select and invoke 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 the schema already documents all parameters thoroughly. The description adds useful context about aliases and requiredness, but this is largely redundant with the schema. It does not materially deepen understanding of parameter semantics 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 clearly identifies the tool as returning parsed SEC Form 3/4/5 insider transaction activity for a US public company, specifying who traded, direction, price, and resulting holdings. It distinguishes itself from raw-filing tools by emphasizing 'parsed into structured transactions' and by implying it is the authoritative source for this specific data.

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 provides example queries ('insider buying at $TICKER', 'did executives sell recently') and points to the alternative tool for raw filing lists: 'For the raw filing list use edgar_company_filings with form_type:"4".' This gives an agent clear when-to-use and when-to-use-other 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: the put_call/direction warning (never report a put as a holding), the notional-vs-premium caveat for options, the whole-USD vs thousands change for pre-2023 filings, and the instruction to rank by pct_of_long_equity and read position_summary/interpretation_note. This is exactly the kind of non-obvious behavior an agent needs.

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 dense but every sentence earns its place: scope, examples, use cases, caveats, and ranking instructions. It is front-loaded with the core purpose and the manager-vs-stock distinction. It is longer than average, but the complexity of 13F data justifies the length; the put_call warning alone prevents a serious reporting error.

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 lookup tool with no output schema, the description covers everything an agent needs to call it correctly and interpret results: input format, examples, scope limitations, value units, option semantics, and ranking guidance. The only minor gap is that it doesn't describe the exact JSON shape of the response, but the description's mention of fields (value, shares, pct_of_long_equity, position_summary, interpretation_note) compensates.

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 schema already documents all four parameters. The description adds value by clarifying that ticker_or_cik (and its aliases) refers to the manager, not the held stock, and by giving concrete CIK examples. It also explains the meaning of the returned value field (whole USD vs thousands), which is not in the schema. It doesn't add much about `limit`, but the schema already covers that.

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: it returns the authoritative 13F-HR portfolio of an institutional manager, with share counts, position values, and report period. It explicitly distinguishes the manager (the filer) from the held stock, and gives concrete examples (BRK-B, Bridgewater CIK). This clearly differentiates it from siblings like edgar_fund_holdings and edgar_company_facts.

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 examples ('what does Berkshire own', 'Bridgewater's biggest positions', 'which funds hold $TICKER') and states the key input requirement: pass the MANAGER's ticker or CIK, not the held stock. It also notes the run-per-manager behavior and the 13F scope (US-listed long equity, >$100M AUM, ~45-day lag), which helps an agent decide when this tool is appropriate versus 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it discloses that not every filer discloses product-level revenue in XBRL, that a small fraction use a non-standard table layout the parser can't read, and that both cases are reported as an explicit status rather than a silent empty array. It also explains the automatic form resolution and the resolved_form output field. This is strong behavioral transparency, though it doesn't detail rate limits or exact error statuses.

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 dense but well-organized, front-loading the core purpose and differentiation before diving into parameters and edge cases. Every sentence earns its place: the first sentence states the purpose, the second differentiates from siblings, the third explains the data source, the fourth covers filtering, the fifth covers citations, and the sixth covers failure modes. It's longer than ideal but the length is justified by the tool's complexity and the need to distinguish it from closely related siblings.

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 7 parameters, no output schema, and significant complexity around XBRL dimensions and form types, the description is remarkably complete. It covers what the tool returns (structured rows with citations), how to filter, which form types are supported, how resolution works, what the resolved_form field means, and what happens in failure cases. The only minor gap is not describing the exact output row structure, but the description's mention of 'pre-parsed into rows' and 'citation (accession, filing date, exact report + URL)' provides sufficient context for an agent to understand the return shape.

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 7 parameters thoroughly. The description adds value by explaining the semantics of product_filter (case-insensitive substring matched against the dimension breadcrumb), the form_type fallback order, and the alias relationships between ticker_or_cik, cik, and ticker. It also clarifies that ticker_or_cik is effectively required despite the schema listing 0 required parameters. This goes beyond the schema's individual field descriptions.

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

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

The description opens with a specific verb and resource: 'PRODUCT-LEVEL or segment-level revenue as STRUCTURED data' and immediately gives concrete example queries ('how much revenue did Keytruda generate', 'AAPL revenue by product line'). It explicitly distinguishes itself from sibling tools edgar_company_concept and edgar_company_facts by explaining that those tools only expose undimensioned totals while this one reads dimensional XBRL data. This is a clear, specific purpose that an agent can act on.

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

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

The description explicitly states when to use this tool vs alternatives: 'Regular XBRL tools (edgar_company_concept, edgar_company_facts) only expose UNDIMENSIONED totals... which those APIs cannot see no matter which concept is requested.' It also names the fallback tool (edgar_filing_text) for cases where the parser can't read the table. It explains form-type resolution (10-K, 20-F, 40-F, 10-Q) and the product_filter behavior. This is exemplary usage 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it returns specific fields (entity, CIK, dates, accession number), explains the significance of the 8-K 'items' array, and notes that results can be fed directly into edgar_filing_text/documents without a second lookup. It does not mention rate limits or pagination, but with the safety profile already annotated, the added context goes beyond the minimum.

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 dense but well-organized, front-loading the most important guidance ('PREFER OVER WEB SEARCH') and authoritativeness. It packs substantial detail (return fields, 8-K items, downstream chaining) into a compact paragraph without fluff. Slightly longer than necessary but every sentence earns its place given the tool's complexity.

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

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

Given the tool's complexity (5 params, output schema, many siblings), the description is highly complete: it explains the tool's scope, return value highlights, how to chain with related tools, the 8-K item codes' signal value, and explicitly contrasts with the company-specific alternative. The output schema covers return structure, so the description doesn't need to restate it. No significant 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?

Schema description coverage is 100%, with each parameter already described (query, limit, form_type, start_date, end_date). The description adds minor clarifications like mapping form types to annual/quarterly/current event and notes the date range, but this mostly repeats schema information. The accessory number 'feed straight into' detail relates to return values, not parameter semantics, so the description adds little 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 uses a specific verb ('search') and resource ('SEC filings' via EDGAR's full-text index), clearly stating it is the authoritative tool for finding filings that mention a topic. It distinguishes itself from the sibling edgar_company_filings by noting it searches across the whole market rather than for a specific company.

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 'PREFER OVER WEB SEARCH' for certain query types and gives an exclusion: 'not for a specific company (for that use edgar_company_filings)'. This provides clear when-to-use and when-not-to-use guidance, including a named alternative.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the bar is lower, but the description adds meaningful behavioral detail beyond annotations: cheap to call with no rate limit concerns, returns a structured result including `alternatives` for name matches, and carries a `next` hint pointing to edgar_company_snapshot. No contradiction with annotations.

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

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

The description is longer than average, but each part earns its place: purpose, call-order guidance, return shape, explicit-use caveat, and follow-up hint. It is front-loaded with the primary purpose and the call-first instruction, then layers in progressively finer details without 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?

Given the tool's moderate complexity, the rich annotations, and the presence of an output schema, the description is complete enough for correct invocation. It covers aliases, when to avoid explicit use, cost/rate-limit characteristics, return shape, and even the recommended next step, leaving no practical gap for an 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 description coverage is 100%, so baseline is 3, but the description adds value by explaining alias semantics (`ticker`, `company`, `ticker_or_cik`), giving concrete examples (AAPL, TSLA), and clarifying the edge case that passing a bare CIK has nothing to look up because this tool resolves to a CIK.

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

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

The description clearly states a specific verb and resource: 'Resolve a US stock ticker OR a company name to the SEC's 10-digit CIK identifier'. It also names the downstream SEC tools that depend on this resolution, distinguishing this tool from siblings like edgar_company_filings and edgar_company_concept.

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 ('Call THIS FIRST when you have a ticker/name and need to use ...') and equally explicit when-not-to-use guidance ('only use it explicitly when you want the CIK as data'). It also notes that most other tools accept tickers/names directly and call this internally, which prevents unnecessary chaining.

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, openWorld, idempotent, and non-destructive. Description adds details: returns sorted descending, concept is a US-GAAP tag, period formats explained, and behavior across every filer.

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 clear sections and examples, but slightly verbose. Every sentence adds value, though a minor reduction 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?

Given 6 parameters and no output schema, the description fully covers usage, parameters, return behavior (sorted descending, limit 200), and examples. No gaps 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?

Despite 100% schema coverage, description provides rich context for concept (examples), period (CY2023 vs Q1 vs I), and unit (shares, USD-per-shares), 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 the tool compares one financial metric across all public companies for a single period, distinguishing it from sibling tool edgar_company_concept (one company over time).

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 recommends this tool over web search for cross-company financial comparisons and ranking, and contrasts with edgar_company_concept for when to use each.

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 cover the safety profile (readOnly/idempotent/openWorld/non-destructive), and the description adds substantial context beyond them: the three-state sources_used/sources_failed/sources_skipped model, the meaning of an empty section, the PatentsView soft-fail, and the deliberate Purple-Book skip. This is exactly the operational detail an agent needs.

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 useful use-case examples are front-loaded, but the body is a single enormous sentence with deeply nested parentheticals (the diluted-EPS cover-page aside, the fallback-tag aside, the Purple-Book aside). The density of genuinely relevant detail does not excuse the wall-of-text structure that makes it hard to scan.

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

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

With no output schema and a highly complex multi-source fan-out, the description carries the burden well: it enumerates every returned section, the per-source state tokens, and the name-resolution behaviour. An agent knows what to expect back and how to interpret partial results.

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

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

Schema coverage is 100%, so the schema already documents type/value/country, and the description largely restates that (type interchangeability, accepted value shapes). It adds some real meaning — country 'only affects a NAME lookup' and the resolved:false path for private companies — but not enough to exceed the baseline 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 — a 'full cross-source profile of a US public company in ONE parallel call' — and enumerates the exact data legs (SEC EDGAR, XBRL, USPTO, USAspending, etc.). It clearly distinguishes itself from siblings like company_facts, deep_research and resolve_entity by covering the holistic-view use case.

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 selection rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' with concrete trigger phrasing ("Tell me about X", "research Acme"). The alternative and the condition that selects it are both stated.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior, and the description adds substantial beyond-annotation context: results carry provenance (accession number, filing date, exhibit URL), the status distinguishes 'no Exhibit 21' from lookup failure, data comes straight from SEC, and subsidiary names use '&' not 'and.' No contradiction with annotations.

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

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

The description is a dense single paragraph, but it is front-loaded with the core function and reverse relationship, then moves through the use case, a concrete example, filter behavior, provenance, and limitations. It is longer than minimal, but each sentence carries useful information and there is no 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 complex SEC-lookup tool with no output schema, the description covers what the caller receives, how to audit results via provenance, how to filter, and a known coverage gap (Foreign private issuers). An agent has enough context to select the tool and interpret unusual outcomes like a missing Exhibit 21.

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%, and the schema already documents aliases, the limit range, and name_filter's case-insensitive substring behavior. The description reinforces the aliases and the use of name_filter, but adds little parameter meaning beyond what the schema already provides, so 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 names a specific verb and resource: given a US-listed public filer/parent company, list its operating subsidiaries disclosed in Exhibit 21 of the most recent 10-K. It also explicitly frames itself as the reverse of sponsor_to_filer, clearly distinguishing it from the closest sibling tool.

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

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

The description explicitly contrasts this tool with sponsor_to_filer, explaining that this is the one-call direction for getting a parent's full subsidiary list, versus '~10 calls guessing candidate subsidiary names and confirming each via sponsor_to_filer.' It also gives the specific name_filter use case for checking a candidate entity, and notes the Foreign private issuer exclusion.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety and write profile are covered. The description aligns with those hints but adds little behavioral context beyond the use cases; it does not, for example, state whether deleting a missing key is an error or what the response looks like. With annotations carrying the main burden, a 3 is appropriate and there is no contradiction.

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

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

Two sentences with no filler: the core action and key-based scoping come first, followed directly by usage guidance and sibling pairing. Every sentence earns its place.

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

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

For a simple deletion tool with a fully documented schema, explicit destructive/idempotent annotations, and no output schema obligations, the description covers what an agent needs: what it deletes, when to use it, and how it relates to remember and recall. Nothing critical 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%, and the schema already explains that key, k, name, and label are aliases for the memory key. The description adds no parameter-level details, but since the schema fully documents the single meaningful parameter, it does not need to; baseline 3 is correct.

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

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

The description opens with a specific verb-resource pair: 'Delete a previously stored memory by key.' It clearly distinguishes the tool from its siblings remember and recall by naming them and positioning forget as the deletion counterpart, so an agent can select it correctly 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?

The description gives explicit triggering conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names the complementary tools remember and recall, routing the agent to its siblings and making the when-to-use decision unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by explaining that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It does not cover failure modes or rate limits, but the annotation coverage lowers the bar for this dimension.

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

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

The description is three sentences: purpose, process, and use cases. It is front-loaded with the core action, contains no fluff, and every sentence earns its place.

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

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

For a two-parameter tool with no output schema, the description is sufficient: it specifies the output format ('single text blob ready to drop at site-root/llms.txt'), the process, and the use cases. Minor gaps like error handling are not critical given the tool's simplicity.

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 fully documents both url and max_links. The description does not add parameter-specific semantics beyond what the schema provides, which is acceptable; the baseline of 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 ('Generate') and resource ('llms.txt file for any URL'), and explains the process (fetch, extract, emit). It does not explicitly contrast with siblings like ai_visibility_check, but the purpose is unambiguous and clearly distinct from the other tools.

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

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

The description provides concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use it. It does not mention when to prefer a sibling or any exclusions, so it stops short of a 5.

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 goes far beyond the annotations by disclosing non-obvious behavioral traits: markets settle on Weather Company, not NWS; station is derived from settlement clause; forecast_prob uses an assumed normal distribution; edge_pp is gross; and it exposes a concrete measured result showing the market beat the forecast. These are exactly the kind of caveats an agent needs to interpret results correctly, and they are not visible in the read-only/open-world 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 packed with critical trading caveats. It is front-loaded with purpose and modes, then structured warnings (1-4), then a measured result, followed by edge-case handling. While not concise, the density is justified given the financial stakes and the need to prevent misuse; it could be slightly more scannable with headers, but overall each sentence carries weight.

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 must specify return values, and it does: LIVE mode returns the strike ladder with market_prob, forecast_prob, edge_pp, and the settlement clause; BACKTEST returns brier_market vs brier_forecast, settlement-vs-forecast basis, and a plain-English verdict. It also covers international and precipitation fallbacks, and the warning section covers all major edge cases. Nothing an agent needs to call the tool correctly is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning to each parameter: 'city' includes a default and fallback behavior (unmapped cities return known_cities[]), 'date' explains open/close timing, 'market_type' clarifies precipitation returns no forecast, 'backtest_days' explains the scoring methodology and max, and 'series_ticker' overrides city. This is a textbook example of enriching schema with operational context.

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

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

The description clearly states the tool's function: 'Prices Kalshi daily high-temperature markets against the NWS forecast...' and explicitly defines two modes (LIVE and BACKTEST) with distinct outputs. It differentiates itself from sibling tools by focusing on a niche weather-edge analysis, and the many specific details (station codes, edge_pp, brier scores) leave no doubt about its purpose.

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

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

The description provides explicit when-to-use guidance: 'LIVE (default)' vs 'BACKTEST (`backtest_days: N`)', and tells the user to run backtest before believing any edge. It also covers exclusions: international series return forecast_unavailable, precipitation is not priced, and it warns about using city-centre forecasts when stations are derived from settlement clauses. This is model-guidance beyond what any sibling alternative offers.

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, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail by scoping to the caller's active subscriptions and enumerating the returned fields, which goes beyond what annotations provide.

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

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

Two sentences carry all the essential information: what the tool lists, what it returns, and when to use it. The primary action is front-loaded and there is no redundant wording.

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

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

For a simple read-only list tool with one optional documented parameter and no output schema, the description is complete: it names the resource scope, the returned fields, and the use cases. Nothing critical 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 single optional include_inactive parameter is already fully documented. The description does not add further parameter context, which matches the baseline of 3 for high schema coverage.

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

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

The description names a specific verb and resource: 'List the caller's active subscriptions.' It also lists the exact return fields, making the operation concrete and clearly distinct from sibling tools like subscribe and unsubscribe.

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 when to use this tool: 'review what you're monitoring before adding more' and 'find an id to cancel.' It gives clear context, though it does not explicitly name sibling alternatives or state when not 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?

Goes far beyond the annotations: discloses the claim_token return-and-lookup flow, rate limit (5/day/identifier), cost (free, no quota), and operational facts (team reads digests daily, signal affects roadmap). Also instructs on content policy (describe in terms of Pipeworx tools, don't paste user prompts). No contradiction with annotations.

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

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

Dense but every sentence earns its place: purpose is front-loaded, the critical exclusion comes early, then workflow, then operational constraints. The length is justified by the tool's nuance (claim tokens, rate limits, server-scoping) and there is zero 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?

Despite no output schema, the description fully covers what an agent needs: when to call, what to include, what to expect (claim_token), how to follow up later, and operational limits. No important behavioral aspect is left unexplained.

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 parameters at 100%, giving baseline 3. The description adds real value beyond schema by explaining the claim_token round-trip workflow and the message content rule (mention specific tool/pack, avoid pasting user prompts). These clarify how to use the parameters correctly, lifting the score above baseline.

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 opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the three content categories (bug, feature/data_gap, praise) and explicitly excludes tools from other MCP servers, so an agent can immediately distinguish this from any sibling or external 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?

Gives explicit when-to-use conditions (wrong/stale data, missing catalog entry, positive experience) and an explicit when-not-to-use with an alternative action: file with the other server instead. Also provides a disambiguation heuristic ('Pipeworx tool names are the ones this connection lists'). This is exemplary routing guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that the data is self-aggregating, derived from CF analytics-engine, contains no PII, and only exposes (pack, tool, count). It also states caching behavior (5min-1h depending on window), which is useful operational context not present in 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 front-loaded with the core result set, then uses a compact numbered list for use cases. Every remaining sentence adds substantive value — data source, privacy, and caching — with no filler or repetition beyond the minor window mention.

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

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

For a simple one-parameter read-only tool, the description fully covers what the agent needs: what it returns, what windows are available, how the data is derived, and that it is privacy-safe. The absence of an output schema is adequately compensated by naming the return components (top tools, top packs, total call volume).

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 for the single optional window parameter is 100%, including the enum values and an explanatory description that already notes the default and the hot-vs-steady-state tradeoff. The description reiterates the window options but does not add meaning beyond what the schema already provides, so the baseline score of 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 opens with a clear purpose — what other AI agents are calling on Pipeworx right now — and specifies the exact deliverables: top tools, top packs, and total call volume over a window. This is a specific resource plus a concrete return set, making it easy to distinguish from sibling tools like discover_tools or recent_alerts.

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 three explicit use cases: discovering hot data sources, confirming a canonical tool, and aligning with aggregate agent behavior. It does not explicitly say when not to use it or name an alternative, but the 'Useful for' list gives clear contextual guidance for choosing 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 mark readOnly/idempotent/non-destructive, and the description goes far beyond them: fee calculation assumptions, category-specific taker fee rates, gas modeling, fee_basis provenance, fallback behavior, fill_check repricing against live depth, and the warning that net_positive:false is a correction rather than a regression. This is unusually transparent about edge cases and limitations.

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

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

The description is long but densely packed and sectioned with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FEES, FILL CHECK) that make the content scannable. Every sentence contributes decision-relevant information, and the most important usage guidance is front-loaded before deeper fee and fill 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 complex analytic tool with no output schema, this description is remarkably complete: it covers all invocation modes, return fields (opportunities[], partition_check, fee fields), fee modeling, filtering behavior, fill-check semantics, and constraints. An agent has enough information to call the tool correctly and interpret its results without external lookups.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: event accepts Polymarket slugs or full URLs, topic expects a seed question, and the no-arg case is documented even though it is not a schema parameter. It also explains what each mode does with its input and what signal it produces.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It further distinguishes three invocation modes (no-arg trending_scan, event, topic) and names polymarket_fill_risk as the custom-sizing alternative, so an agent can unambiguously tell this tool apart from its 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?

Usage conditions are explicit: no args for trending scan, event 'recommended for a specific market', topic for cross-event scanning. It also explains why cross-event mode catches patterns single-event misses and redirects to polymarket_fill_risk for custom sizing, leaving no ambiguity about when to choose each path.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds a wealth of behavioral context beyond that: it explains caching at the KV level (1h, keyed on all knobs), the response segmentation into by_segment with diagnostics, the fee handling (net of slippage and taker fee, with fees_pp_applied itemized), and the 'rare-by-design' concentration longshot gate. It even explains the logic behind excluding fed bets. This is far more than annotations provide.

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, extremely dense paragraph with heavy use of all-caps, abbreviations, and parentheticals (e.g., FIVE MODEL FAMILIES, edge_pp_net, fees.ts). While every sentence carries information, the structure is not appropriately sized for a tool description; it buries key facts like caching and diagnostics in a wall of text. It could be formatted with headings and bullet points for easier scanning. Although the content is valuable, it violates conciseness by requiring significant effort 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?

Given the tool's complexity (9 parameters, no output schema, multiple model families) and that annotations only cover safety, the description is remarkably complete. It explains the three response segments, diagnostics, fed_candidates, the net-of-fee edge calculation, the role of each knob, and the caching behavior. An agent can understand what the tool returns and how to invoke it correctly without needing additional context.

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

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

Though schema_description_coverage is 100%, the description adds significant semantic depth. For example, it explains that min_partition_leg_kelly applies to per-leg Kelly within top_legs and that partition arbs return kelly_fraction_half=0 at parent level by design—details not in the schema. It also clarified the interaction between slippage_pp and the Polymarket taker fee, and the purpose of tradeable-edge knobs. This goes well beyond the schema's own descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovery from Pipeworx data vs. market pricing. It also states its intended use case ('what should I bet on today'), making it 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 clear context for when to use the tool—for betting opportunity discovery—and even explains why Fed bets are excluded from ranking due to unreliable data. However, it does not explicitly name alternatives or say 'use this instead of X when...', so it lacks explicit exclusions. The 'Built for' phrasing implies usage but does not cover when not 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 mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: snapshot gap semantics, TTL limits, fee-inclusive decay computation, the signed nature of edge_pp_net, expired[] lifecycle meaning, and the fact that decay uses daily closes rather than intraday data. No contradictions 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 long but densely organized into Args, RESPONSE, and LIMITS sections, with the core purpose front-loaded. Some rhetorical flourishes ('the median lifespan is your competition clock') add color but not operational necessity. It earns a high score for structure, though it sacrifices some 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?

With no output schema, the description fully carries the burden of explaining return values and edge cases. It explains tracked[], expired[], snapshot_dates[], data gaps, history depth limits, and fee/slippage treatment. An agent has everything needed to call this correctly and interpret the response.

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 both days and window fully. The description restates defaults and adds a 'max 30' note for days and the snapshot-family concept for window, but it does not introduce meaning beyond the schema's parameter descriptions. 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 states a specific purpose: edge persistence and decay telemetry from daily polymarket_edges snapshots, and answers a concrete question ('how long has this edge existed and is it shrinking?'). It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence/decay rather than current edge values.

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 clearly establishes when to use the tool: when an agent needs edge longevity, trend, and decay rather than just current edge values. It even explains why this matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it never explicitly names alternatives or states when not to use it, so it falls just short of full explicit routing guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses operational behavior: it walks the order book, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), models depth-crossing cost, and explicitly states fees are NOT modelled (gross vs net). It also warns about forced_directional_risk and thin books, adding 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?

The description is long but well-structured, with clear sections (SINGLE-MARKET, BASKET, fees note) and no redundant filler. It is front-loaded with the core purpose and then provides mode-specific details. While it could be trimmed slightly, the length is justified by the tool's complexity and the need to convey both modes and caveats.

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 must cover return values, which it does thoroughly (listing all fields for both modes). It also explains the fee implication and when the tool is applicable, making it complete for an agent to call correctly without needing to inspect schemas or other sources.

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 4 parameters, but the description adds meaning beyond that: it explains the difference between single-market and basket interpretation of size_usd (max spend vs settlement notional), the auto-selection for side in basket mode, and the format of market/event (slug or URL). This enriches the schema's bare descriptions.

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

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

The description states a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes between single-market and basket modes. It explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) and tells the agent when to use this tool over them, making 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 provides explicit when-to-use guidance ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains the rationale (theoretical overround not capturable, partial fills create unhedged positions). It also explains how to choose between single-market and basket modes based on input types.

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

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

The description is exceptionally transparent about behavioral nuances: it discloses the two modes, the matching logic, the safety fields and their meanings, fee calculation details with verification dates, resolution equivalence methodology, and historical changes that affect interpretation (e.g., fleet #1927 correcting gas modeling). It also explicitly states limitations (spread-crossing cost not modeled, no live order book). Annotations already indicate read-only/idempotent, and the description adds extensive context 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 extremely verbose—it reads as a full technical spec with historical fleet notes and extensive caveats. While it is front-loaded with the core purpose and organized with section headers, its length (several hundred words) is far from concise. Every sentence adds information, but the sheer volume makes it heavy for an agent to parse. A more distilled version would be more efficient.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains all response fields (spread, compatibility_warning, fees, resolution_audit, etc.), defines every safety code, describes fee formulas with verification dates, and covers both modes and edge cases. An agent has everything needed to invoke the tool correctly and interpret results, even without an 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?

Although the schema already provides 100% coverage of parameter descriptions, the tool description adds substantial semantic value: it explains the topic aliases and keywords, how resolution.topic_matched_by distinguishes exact/alias from phrase/token guesses, and the behavior of explicit overrides. It also clarifies that unresolvable topics return a specific error rather than falling back. This goes well beyond the schema's baseline.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly defines the tool's function and distinguishes it from single-venue tools by its focus on cross-venue comparison. The two operational modes are explicitly described, leaving no ambiguity about what the tool does.

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

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

The description explains when to use the tool (for cross-venue spread analysis) and details both usage modes with examples. It provides clear guidance on how to interpret results and warns that 'pre-mapped ≠ tradeable'. It also points to alternative tools like resolution_audit/resolution_diff for specific needs. However, it does not explicitly state when NOT to use this tool in favor of siblings, so it stops short of a full when-not/alternatives matrix.

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 and the bar is lower. The description adds genuine value by disclosing the dual behavior (retrieve vs. list-all-keys when omitting the argument) and the scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID). No contradiction with annotations.

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

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

Three sentences with zero waste: core action first, then usage context with examples, then scoping and sibling pairing. Every sentence earns its place, and the key behavioral distinction (omit key to list all) is front-loaded.

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

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

For a low-complexity read/list tool with annotations carrying the safety profile and a schema fully documenting the parameters, nothing an agent needs to call it correctly is missing. The dual behavior, scoping, and sibling relationship are all covered despite the absence of an 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 schema fully documents all four parameters (which are all aliases for the same key). The description's note about omitting the key to list all keys is mirrored in the schema, so it adds little beyond what structured data already provides. Baseline 3 is appropriate since 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 ('Retrieve a value previously saved via remember, or list all saved keys') with concrete use examples (target ticker, address, research notes). It explicitly differentiates from siblings by naming remember (save) and forget (delete), so an agent can distinguish recall without inspecting other 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 clear context on when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and routes to alternatives ('Pair with remember to save, forget to delete'). It lacks an explicit when-not statement, but the scoping and sibling pairing make the intended usage unambiguous.

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds genuinely useful behavioral context beyond that: return fields (source, citation_uri, raw payload), the mark_read side effect that affects subsequent calls, and polling suitability. No contradiction with annotations is present.

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

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

Four dense sentences, each earning its place: the opening states the core action, the second details return contents, the third covers filtering and mark_read semantics, and the fourth mentions polling and an alternative endpoint. It is front-loaded and contains no 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?

Without an output schema, the description compensates by describing the return payload. It also covers filtering, mark_read behavior, polling, and alternative access. Minor omissions like limit defaults and unread_only details are already present in the schema, so the description is nearly complete for a read-oriented 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%, so the baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), specifying ISO format for since, and explaining the consequence of mark_read ('so the next call only shows newer ones'). This exceeds what the schema descriptions alone provide.

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 uses a specific verb and resource ('Pull fired events from your subscription feed') and clarifies it returns recent alerts from the evaluator's persisted feed. It is conceptually distinct from siblings like list_subscriptions or recent_changes, but it never explicitly names or differentiates those alternative tools, so it falls short of a 5.

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

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

The description gives clear usage context: it says polling works fine, explains the mark_read pattern for advancing to newer events, and points to the GET registry.pipeworx.io/alerts.json endpoint as an alternative for scripts and dashboards. However, it does not explicitly contrast with sibling MCP tools, so it lacks full 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it fans out to multiple sources in parallel, has a GDELT→GNews fallback, notes the PatentsView API sunset causing soft-fail, and describes the return shape (changes[] grouped by source, total_changes, pipeworx:// citation URIs). It doesn't detail pagination or rate limits, but the disclosed behavior is substantial.

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 dense but well-organized: example queries first, then the core function, then source details, then parameter formats, then return shape, then the sibling distinction. Every sentence adds information, though the source-fallback details make it slightly long. The front-loading of example queries is effective for an agent scanning for intent.

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, idempotent tool with 100% schema coverage and no output schema, the description covers the main things an agent needs: what it does, what inputs look like, what sources it hits, and when to use the sibling instead. It doesn't specify pagination or exact output field types, but the return shape is summarized and the annotations cover safety. A small gap is not explaining how 'changes' are structured beyond grouping by source, but this is acceptable given the tool's complexity.

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 schema already documents all three parameters. The description adds meaning by explaining the `since` accepted formats (ISO date or relative shorthand) and giving typical usage ('30d' or '1m'), plus clarifying that `value` can be a ticker or zero-padded CIK. This goes beyond the schema's descriptions and helps an agent construct valid 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 opens with concrete natural-language queries ('What's new with X', 'latest on Y') and then states the exact function: a change feed for a company over a time window in one parallel call. It names the data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly contrasts with entity_profile, so an agent can distinguish it from the closest sibling 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 via example queries, specifies the `since` window formats, and states the alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also discloses fallback behavior (GDELT preferred, GNews on rate-limit/5xx) and the USPTO soft-fail, which helps an agent decide whether this tool fits the task.

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 readOnly/idempotent safety profile, but the description goes far beyond: ≤60s cache TTL, no push/webhook, per-category data sources and their failure modes (SEC usually finds nothing, court ALWAYS empty with unsupported:true), the resolves_on_this_release honesty contract, matched_by mechanism disclosure, and the empty-window response shape. This is unusually rich behavioral disclosure.

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?

It is front-loaded with the core definition, but the body is an extremely long block with repeated warnings (empty windows, no arbitrage, cache limits) that could be consolidated. Most sentences earn their place, but the density and repetition hurt scannability for an agent choosing a tool.

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

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

Given an output schema exists, the description needn't explain returns, and it still covers edge cases (empty window shape, zero-match releases, date-only categories) that an agent needs to call and interpret this correctly. Nothing material 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 CATEGORIES discussion adds real meaning the schema does not: what each category actually queries (fred_release_dates, fomc_calendar, pdufa_catalysts, federal-register recent_rules), why court is always empty, and the default semantics of omitting categories. That compensates above baseline.

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 operation — a JOIN of the official release calendar against live Polymarket/Kalshi markets — and states the output intent (which releases land in the next N hours and which markets resolve on them). It explicitly frames itself as a POSITIONING tool, distinguishing it from sibling speed/resolution tools like resolution_audit.

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 says when to use it ('see what is coming and what is already priced'), when NOT to use it ('do not use this to try to beat a release', no push/webhook), and routes the caller to resolution_audit / resolution_diff before sizing positions. Sibling alternatives and exclusions are both 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 idempotentHint=true and destructiveHint=false, so the description adds useful extra context: memory is scoped by identifier, authenticated users get persistence, and anonymous sessions retain memory for 24 hours. No contradiction with annotations.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds value: usage trigger, storage model, persistence behavior, and related tools. No 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?

Given the simple write-tool nature, the absence of an output schema is not a serious gap. The description covers what to store, when to store it, persistence limits, and sibling operations. A marginally stronger version would state return behavior or overwrite semantics.

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 documents the key/value aliases and examples. The description only restates the key-value concept without adding deeper semantics, so it meets but does not exceed the baseline for high schema coverage.

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: 'Save data the agent will need to reuse later.' It clearly differentiates itself from sibling tools by naming recall (retrieve) and forget (delete), so an agent can tell which operation to invoke.

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 trigger condition: 'Use when you discover something worth carrying forward...' and lists concrete examples. It does not state when not to use it, but the guidance is clear enough for most cases.

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

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

Beyond the read-only and open-world annotations, the description discloses the evidence verification model, status semantics, cost refusal behavior, zero-cost empty-source behavior, and failure signals like model_output_empty. It also distinguishes a legitimately absent leadership page from a page that was never checked.

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 dense but front-loaded with the core operation and evidence contract. Every sentence carries useful information, though the single long paragraph could be easier to scan if split by source, cost, and status behavior.

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, multi-source research tool with no output schema, it covers return shape, verification statuses, cost caps, source behavior, and common failure modes. An agent has enough information to invoke it correctly and interpret ambiguous-looking 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?

Even though the schema already documents parameters, the description adds operational meaning: max_cost scales page fetching and is refused below a floor rather than overspent, web requires entity.domain, and output_schema fields are wrapped in value/evidence_url/quote/status.

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, answering one question about one company and returning evidence-wrapped JSON. It clearly distinguishes the tool from classify_row and explains that the output matches a caller-supplied 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 explicitly says when to use this tool: fixed question plus schema across many rows with a hard cost cap, and when to use the alternative classify_row for fixed-label classification. It also explains source-selection conditions for web, catalog, and both.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: deterministic regex + vocabulary with no LLM pass, confidence:'low' for unusual clauses, reuse of bet_research's cancellation_rule detector, and the known gap of returning evidence_standard:'unspecified' rather than guessing. No contradiction with annotations.

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

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

The description is long but dense and front-loaded: the first sentence carries the core purpose and output fields, then input semantics, usage context, companion tool, and known gap follow in logical order. Every sentence contributes necessary information with no 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?

With no output schema, the description carries the full burden of explaining what the agent gets back. It enumerates the extracted fields, the confidence fallback, the evidence_standard enum values, void_handling reuse, and the known limitation, making the tool fully callable without guessing.

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 description still adds meaningful value: concrete examples for Polymarket slugs and Kalshi tickers, clarification that Kalshi event tickers fall back to a representative market, and why that fallback is safe. This goes well beyond the bare schema properties.

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: 'Extract the settlement clause of a single Polymarket or Kalshi market.' It enumerates exactly which attributes are extracted (source, clock time, precision, evidence standard, void handling) and explicitly distinguishes this tool from resolution_diff and polymarket_kalshi_spread, making sibling differentiation 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 explicitly states when to use the tool: before treating a polymarket_kalshi_spread row as real arbitrage. It also names the companion tool resolution_diff for comparing two markets, and explains the Kalshi event-ticker fallback behavior, leaving no ambiguity about when or how to invoke 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, openWorldHint, idempotentHint, and destructiveHint=falsechers. The description adds important behavioral nuance beyond those hints: it explains the three-way equivalence outcome, the confidence threshold for comparing, and the specific-versus-generic source rule that prevents false conflicts. It also discloses that the tool internally runs resolution_audit, which is useful to set expectations.

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 information-dense and front-loaded with the core purpose, but it is long and contains a lengthy parenthetical example and an extended heuristic explanation. Every point is relevant, but the phrasing is verbose and could be tightened or restructured with bullet-like separators. It earns its content but sacrifices 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?

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: it explains the possible values of `equivalent` (true/false/unclear), mentions `differing_fields`, and instructs the caller to read `raw_clause` in unclear cases. It also covers the non-conflict heuristic. The only gap is not fully specifying the entire output structure or exact field locations, but the guidance is sufficient for the agent to decide when to call it.

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

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

Schema description coverage is 100% with both parameters described as 'First market to compare' and 'Second market to compare.' The description adds that they are markets on either Polymarket or Kalshi and that the tool runs resolution_audit on both sides, which slightly clarifies roles. However, it does not add meaningful detail beyond the schema's enum and nested-object definitions, so a 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 opens with a specific verb and resource: 'Field-by-field diff of TWO markets' settlement clauses.' It clearly states that the tool runs resolution_audit on both sides and compares source, settle time, precision, and evidence standard, which differentiates it from the sibling resolution_audit. The three-way return value is also summarized, leaving no ambiguity about the tool's core function.

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

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

The description gives explicit usage context: 'Use this before sizing a polymarket_kalshi_spread pair as a real cross-venue arb, or standalone to sanity-check any two markets you suspect settle on different things.' This clearly states when to use the tool. It does not, however, explicitly name alternatives or say when not to use it, so it stops short of a full when/when-not guide.

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

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

With readOnly/openWorld/idempotent annotations already covering the safety profile, the description still adds real behavioral context: graceful degradation when GLEIF or OpenFIGI is unavailable, that unresolved identifiers are surfaced under `unresolved` rather than omitted, that ambiguous instrument names assert nothing and return `figi_candidates`, and that each call cascades through several endpoints. It doesn't discuss latency/rate limits, but the additions are substantive.

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?

Most content earns its place for a genuinely complex multi-source tool, but the presentation is a wall of nested parentheticals that is hard to parse, and the critical routing rule ('Use FIRST') is buried after eight example questions. Front-loading the purpose and constraints would markedly improve scannability.

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 that cascades across EDGAR, GLEIF, OpenFIGI and RxNorm, the description covers supported entity types, identifier sources, ambiguity handling, degradation, and the optional country narrowing. Output schema exists, so return values need not be re-explained.

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 already 100%, but the description goes beyond it: it adds ISIN ('CH0038863350') as a valid company input, which the schema omits, and clarifies the semantic split between the 'company' and 'drug' types. These additions measurably exceed the baseline 3 for fully documented schemas.

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 precise verb+resource — resolve a user-spoken NAME to canonical/official identifiers that other tools require as input — and enumerates the concrete identifier types (CIK, ticker, LEI, FIGI, RxCUI). An agent can tell it apart from lookups like company_facts or entity_profile without opening a schema, and the example phrasings anchor the intent.

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 a strong routing rule — 'Use FIRST whenever you have a name but need an ID' — plus the question patterns that should trigger it and notes that it replaces 2-3 manual lookups. It does not explicitly name an alternative sibling or state when not to use it, so it falls short of the 5 bar.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add context. It explains the mechanism (probes each entity with ai_visibility_check) and the output (ranked list with score, confidence, signal density), which is useful but not extensive. No contradictions 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?

Three sentences with no filler. The core purpose is front-loaded ('Compare AI visibility across multiple entities side-by-side'), followed by mechanism and use case. Every sentence earns its place.

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

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

Given the schema documents all parameters and the description explains the output format and purpose, the tool is adequately described. Minor details like exact ranking criteria are not essential for correct invocation. The description is complete enough for an agent to understand what the tool does and when to use it.

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

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

Schema description covers all 4 parameters at 100%, so the baseline is 3. The description adds no extra parameter semantics beyond what the schema already explains, so no additional value is provided.

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 verb 'Compare' and the resource 'AI visibility across multiple entities', and explicitly differentiates from siblings by mentioning it uses ai_visibility_check and is for competitive audits. It is specific and unambiguous.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and a sample question ('does Claude know about us as well as our competitors?'). It does not explicitly list exclusions or alternative tools, but the purpose is distinct enough that an agent can infer 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context beyond annotations: it explains partial failure handling, the 5-30s first-measurement latency on bundlephobia, and that sources_failed will list timeouts while other data still returns. No contradictions 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 dense but efficient, opening with the core composite purpose, then listing return fields, then noting ecosystem scope and failure behavior. Every sentence earns its place; no fluff or redundancy, and the most critical usage guidance is front-loaded.

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 thoroughly enumerates the return structure (summary block fields, per-advisory detail, links, alternative versions) and error behavior. It also covers latency expectations and scope limitations, leaving no gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both 'package' and 'version' including defaults and scoped package acceptance. The description does not add any additional parameter semantics beyond what the schema provides; the baseline of 3 applies since the schema carries the full 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 clearly states the tool's purpose: a composite check for 'should I add this npm package' covering license, advisories, version history, and bundle size via deps.dev and bundlephobia. It specifies the resource (npm packages) and the exact questions it answers, distinguishing it from siblings like scan_competitor_ai_presence and the deps.dev:version fallback.