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 readOnlyHint, openWorldHint, and idempotentHint; description adds that it routes to 6,431 tools, fills arguments, and returns structured answers with citation URIs. It also notes it works on every tier and is one fast call, which is useful for performance expectations. Does not contradict annotations and provides valuable context beyond them, though some details like rate limits are absent.

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?

Description is long but highly informative, front-loaded with the key directive to prefer over web search, then provides examples and alternatives. Every sentence contributes to guiding the agent. Slightly verbose in the middle with list of domains, but that list is useful for disambiguation. No wasted words overall.

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 routing tool with a single natural-language parameter, the description is complete: covers what to ask, when to use, alternatives, and expected output (structured answer with citations). Although no output schema exists, the description sets expectations for return format. An agent has enough information to decide 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 coverage is 100% (all parameters are aliases for 'question'), and the schema already describes the 'question' parameter as accepting natural language. The description repeats this but doesn't add new semantics like formatting requirements or length limits. Baseline 3 is appropriate since schema carries full load; description adds no parameter-specific value beyond what schema already states.

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

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

Clearly states it answers factual questions about real-world data with sources/citations, and lists specific domains. Differentiates from web search and sibling tools by emphasizing authoritative structured data with citations. The name 'ask_pipeworx' is somewhat generic, but the description fully specifies 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?

Explicitly says 'PREFER OVER WEB SEARCH' and gives concrete when-to-use triggers ('what is', 'look up', etc.). Mentions sibling tools ask_pipeworx_grounded and deep_research as step-up alternatives with conditions. Provides examples of questions to use it for, making usage guidance exceptionally 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context beyond annotations: that this is a full working router (not a stub) and that it carries live experimental routing. This enriches understanding without contradicting 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?

Two sentences, front-loaded with the core purpose and differentiation, then the usage directive, and a final clarification that it is not a fallback. Every sentence earns its place with zero waste.

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 one-parameter tool with strong annotations and a clear explanation of its experimental nature and usage, nothing essential is missing. The response shape is referenced as identical to ask_pipeworx, and the tool's role is fully described.

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% – every parameter is explicitly an alias for 'question' with a clear description. The description adds no parameter information, but the schema fully documents the single logical parameter, 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 clearly states it is a beta version of ask_pipeworx, a universal router with identical tools, arguments, and response shape, but with candidate routing improvements. It distinguishes itself from the sibling ask_pipeworx by being the experimental variant, leaving no ambiguity 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?

It explicitly instructs to use it 'exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide what merges. This gives a clear when-to-use directive and implicitly contrasts with the stable 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the extraction mechanism (only uses tool result), the exact success and refusal response shapes with all possible refusal_reason values, and the extra LLM call cost. 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 well-structured: purpose, behavior, usage, and cost are front-loaded. It's slightly long but every sentence contributes distinct information; minor redundancy with the title is acceptable.

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

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

For a single-parameter read-only tool, the description is exceptionally complete: it covers output format, refusal reasons, usage context, alternatives, and cost. Nothing an agent needs to decide or call correctly is missing.

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

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

The schema already has 100% coverage with clear descriptions and aliases for the single 'question' parameter. The description adds no new parameter meaning beyond what's in the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a hallucination-resistant answer mode for high-stakes reads, distinct from ask_pipeworx by its extraction-only-from-tool-result behavior. It names the sibling tool and explains the difference, making the purpose unambiguous.

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

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

Explicitly instructs when to use this tool (quoted/cited/acted-on answers, high-stakes contexts) and when to prefer ask_pipeworx (casual lookups), including the cost trade-off of an extra LLM call. This is textbook 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 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 only declare safe read-only behavior; the description adds substantial behavioral detail beyond that: it NEVER substitutes periods, NEVER returns 0 for missing data, NEVER lets YTD answer quarterly, and NEVER converts currency. It also discloses data provenance, status semantics, and response contents including concept, accession, restatement trail, and contract version.

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 and fairly long, but it is front-loaded with the core purpose and examples before moving to behavioral guarantees and status semantics. Nearly every sentence adds distinctive information, though some stylistic repetition and capitalization could be trimmed 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?

Despite having no output schema, the description compensates by detailing exactly what every answer carries, enumerating all non-answer statuses, and describing source behavior and restrictions. Combined with the fully documented 9-parameter schema, an agent has enough context to select and invoke the tool 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?

The input schema has 100% parameter description coverage, so the schema already explains period, company, attribute, and other parameters. The description reinforces key ideas like filer-defined fiscal years and the ambiguity handling for company names, but it mostly restates or complements rather than adding substantially new parameter-level meaning.

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

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

States a specific resource and scope: 'financial facts for a US public company for an EXPLICITLY NAMED reporting period,' with concrete examples. It also differentiates itself from entity_profile / get_company_financials by emphasizing deterministic period-matched facts rather than latest figures.

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 instructs 'PREFER OVER entity_profile / get_company_financials whenever the period matters' and explains why those alternatives may return the wrong period. It also enumerates non-answer statuses such as unavailable, unsupported, ambiguous, and conflicting, which clarify when this tool is and isn't 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 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond that by disclosing account/plan requirements, decomposition and parallel routing behavior, the exact return packet structure (evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[]), citation fetchability guarantees, semantic excerpting instead of head-truncation, and expected latency. This is a rich behavioral disclosure that meaningfully extends the annotation coverage.

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 each sentence carries substantive information: account requirement, non-open-web positioning, decomposition, return format, use-case guidance, alternatives, hop iteration, contradictions, citation guarantees, excerpting, and latency. It is front-loaded with the account gating and core value proposition. It loses a point for some redundancy (gap recovery and contradictions are mentioned twice) and overall length, though the complexity of the tool justifies much of it.

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, but rich annotations), the description is remarkably complete. It explains what the tool returns (findings packet with fields, gaps, contradictions, hop, citation_uri), how a citation is always fetchable, when gaps are expected, the differences between depth levels, latency expectations, and when to choose alternatives. An agent has enough context to invoke deep_research correctly without missing critical behavioral or environmental details.

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 adds some value by clarifying that 'depth' controls facet count and hop behavior and that the question accepts broad/multi-part natural language ('decomposition is the point'), but most of the depth semantics are already in the input schema. It does not significantly compensate beyond what the schema already documents, so a 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 and resource: 'Grounded multi-source research across Pipeworx's 1680 STRUCTURED data sources' in one call, decomposing questions into facets and parallel-routing to 6,431 tools. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, naming the exact difference. An agent can immediately tell this is the multi-source structured-data research 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 gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides a clear prerequisite/alternative: 'If you are not signed in, use ask_pipeworx instead'. No inference is 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 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description discloses important behaviors: Q4 rows are derived (FY minus Q1-Q3, marked derived:true), the `latest` field returns the newest 10-Q when fresher than the last 10-K, and results come back newest-first with fiscal_period and form labels. It also explains tag resolution (post-ASC-606) — all useful behavioral context not present in 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 well-structured: it opens with the core purpose, then explains input semantics, then return behavior and usage examples. Some redundancy exists (e.g., mentioning annual/quarterly return in both the purpose and the behavior sections), but for a complex tool with many nuances the length is justified. It remains readable and front-loaded with the most critical info.

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 (8 parameters, aliases, derived data, period filtering), the description covers all essential operational details: how to specify the company and metric, what the returned structure contains, the meaning of `latest`, and when to use filters. With an output schema present, return-value documentation is covered, and the description fills the remaining behavioral and selection gaps comprehensively.

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 adds value by explaining that `concept` takes friendly names that get resolved to XBRL tags, and that `cik` accepts ticker or CIK with aliases across sibling tools. It also clarifies the `fiscal_year` filtering is based on the filer's own fiscal calendar. This goes slightly beyond the schema's per-parameter 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 and resource: "AUTHORITATIVE historical financials for any US public company." It clearly explains what the tool does (retrieves SEC XBRL filings, resolves metric names, returns annual/quarterly values) and even distinguishes itself by emphasizing official SEC data over "third-party scrapes." This is more than enough to differentiate from sibling tools like edgar_company_filings or 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 usage scenarios: "Use for 'what was AAPL's revenue in 2024', 'NVDA's latest cash position', 'show me long-term debt trend'..." It also provides when-not guidance, such as "do not default to `latest` for a period question" and explains when to use `annual` vs the default. The alias explanations referencing sibling tools (edgar_fund_holdings, edgar_company_filings) further disambiguate usage.

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 cover read-only/idempotent safety, and the description goes well beyond: pagination via max_chars/offset/next_offset, the read-side `raw_truncated` cap on especially large filings, zero-match `search` semantics as a real answer, word-fallback match mode, section fallback with section_found:false, and the silent-wrong-company ticker hazard. 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?

Front-loaded with purpose then progressively narrower guidance, so the most important content reads first. It is long and does duplicate some `search` mechanics already in the schema, but for a 12-parameter tool with alias handling the length is largely 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?

No output schema exists, so the description carries the return-value burden and does so: `text` windowing, `truncated`+`next_offset`, `raw_truncated`, per-match `offset` and `match_mode`. Combined with the mutation-free annotations, 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 baseline is 3; the description lifts it by documenting cross-parameter interactions the schema does not (search runs over the WHOLE document before offset/max_chars windowing, and within the `section` slice when both are given). It adds the phrase-construction guidance ('2-4 word verbatim phrase') and the correct form_type set syntax for '10-K|10-Q'.

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 ('AUTHORITATIVE full text of a SEC filing's primary document') with the transformation applied ('HTML stripped to clean plaintext') and the exact content classes it surfaces (going-concern, ATM facilities, MD&A KPIs). It explicitly distinguishes itself from siblings edgar_filing_documents (exhibits) and edgar_company_concept (structured numbers).

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 routing: prefer `search` over paging for a specific fact, use `section` for a single part, and defer to edgar_filing_documents/edgar_company_concept for other needs. It even supplies representative question phrasings and the accession-vs-ticker/form_type selection rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. 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 already promise a safe read-only, idempotent operation, and the description adds substantial behavioral detail: soft-failing USPTO API until reactivation, sources_used/sources_failed/sources_skipped tri-state semantics, empty sections meaning real no-data rather than bugs, and the SIC-based skip rule for the Purple Book. It also explains name resolution via EDGAR and private-company handling. This far exceeds what annotations convey.

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

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

The description is dense but not bloated: every source, return field, and state has a purpose. It front-loads trigger phrases and the core value proposition before diving into details. The single-paragraph format is a bit heavy, but given the tool's complexity it is structured and readable.

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, and the description compensates by enumerating the return sections, source states, skip reasons, and the resolved/resolved_from/resolved_to details. It also covers input resolution, failure semantics, and the meaning of empty arrays. Nothing critical is missing for an agent to call this tool 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% for both parameters, and the description reinforces and expands on them: type takes company or ticker interchangeably and value can be a ticker, zero-padded CIK, or company name. It provides a concrete example and describes the resolution outcome for private companies, making parameter selection unambiguous. This adds real value beyond the schema.

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

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

The description opens with concrete user phrasings and states a clear mission: build a full cross-source profile of a US public company in one parallel call. It distinguishes itself from single-domain lookups by explicitly naming the fan-out across SEC, XBRL, patents, contracts, FDA, H-1B, news, and GLEIF. The resource and scope are 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 says to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also covers edge cases like private companies returning resolved:false and person/place not yet supported, which helps an agent decide when it is not applicable. It could name more sibling tools like company_facts or compare_entities, but the primary routing rule is clear.

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

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

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 mark the tool read-only, idempotent, and non-destructive, but the description adds far more: ≤60s TTL caching, no push/webhook, empty-window error behavior, court category always empty with unsupported:true, and the honesty contract that releases with zero matched markets are returned rather than dropped. Match labels (true/likely/unclear) and matched_by are disclosed so callers can judge match quality.

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-organized into labeled sections (CATEGORIES, MATCHING AND ITS HONESTY CONTRACT) and front-loads the core purpose. Some clauses are defensive or verbose, such as 'which is an accurate answer, not a bug', but they prevent false bug reports; the density is justified for a multi-source tool with several behavioral 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?

Covers every behavioral edge case a caller needs: category semantics, empty-window error behavior, match confidence labels, timestamp conventions, and how to verify a match before trusting it. Even with an output schema present, the description adds return-value semantics (markets:[], resolves_on_this_release, matched_by, scheduled_at) and is complete for a 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?

Although the schema covers both parameters at 100%, the description adds rich semantic context: what each category means and which underlying source feeds it (fred_release_dates, fomc_calendar, pdufa_catalysts, federal-register), the hours cap and default, and the clock-time conventions for econ vs fed vs FDA/SEC dates. This transforms how an agent should set categories and hours.

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: JOIN of the official release calendar (econ, FOMC, FDA, SEC) against live Polymarket/Kalshi markets, returning scheduled releases in the next N hours and which live markets resolve on them. The 'POSITIONING tool, not a speed product' framing further distinguishes it from arbitrage/spread tools among the 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?

Explicitly says when not to use it ('do not use this to try to beat a release') and names concrete alternatives: call resolution_audit / resolution_diff before sizing anything. It also gives category-selection guidance and warns that a short window should be widened rather than assumed empty.

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?

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?

Discloses far more than the annotations: source systems (EDGAR, GLEIF, OpenFIGI, RxNorm), graceful degradation when enrichment sources fail, disambiguation behavior via figi_candidates, explicit unresolved identifiers, and cascade of multiple lookups. These details go well beyond readOnlyHint/openWorldHint/idempotentHint, and no contradiction exists.

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 examples and the 'Use FIRST' directive, and is organized into clear sections. It is dense and heavily parenthetical, with some explanatory asides that could be trimmed, so it is not a model of brevity but every major section contributes.

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 lookup tool with no output schema, this is unusually complete: it covers supported types, input variants, fallback behavior, edge cases, and what is returned when resolution is ambiguous or fails. An agent has enough context to decide when to call it and what to expect back.

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

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

The schema already documents the basic value forms (ticker, CIK, name, drug brand/generic) and the entity-name-only warning, so the baseline is high. The description adds genuinely useful parameter semantics beyond the schema: ISIN as an accepted input, exact-ticker-map versus name-search matching, and ambiguity handling for names that match multiple instruments.

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 ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), and enumerates concrete example phrasings plus the two supported entity types. It clearly separates the tool from siblings by framing its output as IDs that other tools require as input, so an agent knows when this is the right lookup.

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 instructs 'Use FIRST whenever you have a name but need an ID', which is a clear trigger condition, and gives many natural-language examples that map to calls. It does not name sibling tools as alternatives or give explicit when-not-to-use cases, so it stops short of a perfect 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 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.

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

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

Explicitly states when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides an exclusion: NPM ecosystem only in v1, with PyPI/Maven/Cargo/Go falling under deps.dev:version directly, giving a clear 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap, truncation flagging, and character offsets for verification. This goes beyond the annotations and helps the agent predict output characteristics.

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: it states the core function, the use case, the pairing with a sibling, the embedding/algorithm details, and the input cap. It is front-loaded with the most important information and has 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 search tool with 100% schema coverage and no output schema, the description is complete. It explains the return characteristics (top-N passages, offsets, similarity scores), the algorithm, the size cap, and the truncation behavior. An agent has everything needed to decide when to call it and what to expect.

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 context about the 200K char cap and the nature of the query, but it doesn't add much beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific verb and resource: semantic search inside a fetched record, with a clear contrast to alternatives. It names the sibling ask_pipeworx_grounded and explains the pairing, so an agent can distinguish this tool from the broader ask_pipeworx family 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 explicitly says when to use it: when the record is too big to fit in the prompt, and it names the alternative ask_pipeworx_grounded for grounding over relevant passages. It also gives a concrete workflow: fetch with the gateway, then search within. This is explicit usage guidance with an 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?

Beyond the annotations (read-only, open-world, idempotent), the description discloses key behavioral traits: it returns four distinct statuses ('resolved', 'resolved_via_parent', 'us_registrant_unlisted', 'no_us_registrant'), explains what each means, and emphasizes that it explains why a name does not resolve instead of just returning 'not found'. This goes well beyond annotations.

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

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

The description is front-loaded with the main purpose and efficiently covers key details. While verbose, every sentence is informative and necessary to fully convey the tool's unique value and behavior. It could be slightly shorter but is well-structured.

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

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

Despite lacking an output schema, the description fully explains the return values and their meanings. It also provides the problem context and use case, making the tool's purpose and behavior completely clear. No additional context is needed for an agent to select and invoke it correctly.

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

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

The input schema already describes the single 'sponsor' parameter with 100% coverage and examples. The description adds value by clarifying the types of names accepted (trial sponsors, drug developers, subsidiaries) and providing concrete examples, enriching understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: resolving an organization name (especially clinical-trial sponsors) to the US-listed public filer (ticker + CIK). It explicitly differentiates itself from plain ticker/name lookup by addressing the subsidiary-parent naming gap, making its specific use case clear.

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 this tool: for joining trial sponsors to public financials when plain lookups fail. It provides context about the problem (trial registries using subsidiary names, SEC using parent names) but does not explicitly compare with sibling tools like 'edgar_ticker_to_cik' or 'resolve_entity', though the distinct purpose is implied.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses auth needs, account-type persistence limits, an SMS phone-verification prerequisite, and a 10/day rate cap. No contradiction with annotations; it enriches them with concrete operational constraints.

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

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

The first sentence carries the core purpose, and each following sentence adds operational detail (account requirement, per-type params, delivery rules). It is dense but not bloated, with only mild redundancy against the schema's parameter descriptions and a 'Supported types' list that omits two of the five enum values.

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?

This is a high-complexity tool — five subscription types, three delivery channels, no output schema — and the description covers the essential return value, preconditions, and delivery constraints. Remaining gaps (behavior for patent_grant/clinical_trial, duplicate-subscription behavior) are minor because the schema documents all parameters and the idempotentHint annotation signals retry safety.

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% — the schema already documents all three parameters, including type-specific filter shapes and webhook signing behavior. The description adds interpretive value on top, e.g. items:['5.02'] means officer change and concrete delivery examples, earning one point above the baseline 3.

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

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

States a specific verb and resource ('Create a proactive monitoring subscription to a live-data event stream') and names the returned artifact ('Returns the new subscription id'). The creation focus clearly separates it from lifecycle siblings list_subscriptions and unsubscribe, and from recent_alerts which consumes the feed.

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 clear context for use: proactive monitoring of live data, plus a hard precondition ('Requires a Pipeworx OAuth account — anonymous + BYO cannot persist subscriptions'). It also routes feed consumption to the sibling recent_alerts and the public URL, but never explicitly states when not to subscribe or contrasts with list_subscriptions/unsubscribe.

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 signal read-only, open-world, idempotent, non-destructive behavior, so the bar is lower. The description adds useful behavioral context: it is the onboarding entry point, it returns category-bucketed examples with tool+argument shapes, and it is drawn from the live catalog of thousands of tools. 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 because it lists many user-facing question phrasings and category examples, but this is justified for an onboarding tool. It is front-loaded with the core purpose and then gives focused usage details, though a few phrases are redundant with the 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?

The description is complete for a tool with one optional parameter and no output schema: it explains what the tool returns, how to do a broad query versus a focused query, and when to use it. Minor gaps such as response formatting details are not critical given the tool's purpose.

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 optional `topic` parameter and its allowed values. The description adds examples and clarifies the no-argument behavior, but this mostly restates what the schema already provides rather than adding substantive new meaning.

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

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

The description clearly states what the tool does: returns category-bucketed example questions with the exact tool and argument shape from the live catalog. It positions itself as the onboarding entry point and distinguishes its use from other tools by saying 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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 for when to use the tool: when the agent doesn't know what Pipeworx can do or wants to learn how to call meta-tools. It also explains the tradeoff between calling with no arguments for the full spread versus passing a topic to focus, but it does not explicitly name alternatives or exclusion criteria.

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?

Discloses critical behavioral traits beyond annotations: ownership enforcement, soft-delete behavior ('deactivated not deleted'), and the consequence that historical events remain available via recent_alerts. This adds real context beyond the readOnlyHint/destructiveHint 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?

Two sentences, front-loaded with the action, and no filler. The ownership constraint and deactivation detail each earn their place without bloating the definition.

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

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

For a single-parameter mutation tool with annotations covering safety, the description is fully sufficient. It covers prerequisites, side effects, and downstream visibility of historical data, leaving nothing essential missing.

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

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

The input schema already fully describes the single parameter, including its type and origin ('Subscription id (uuid) returned by subscribe'). The description adds no extra parameter-level meaning, so the baseline 3 applies.

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

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

The description leads with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like subscribe and list_subscriptions by naming the action of cancellation, and further clarifies the scope with ownership enforcement.

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 use: you must have a subscription id, and you can only cancel your own subscriptions. It does not explicitly name alternatives, but the use case is unambiguous and no exclusions are needed.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds significant behavioral context: the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists), the exact percent-delta math for financial claims, and the return structure. It even warns callers not to treat could_not_verify as evidence. This goes far beyond annotations.

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

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

The description is longer than ideal, but every sentence carries weight: trigger phrases, dual-path explanation, verdict list, error semantics, and the efficiency gain. It front-loads the purpose and trigger phrases, and the critical 'IMPORTANT for callers' note is placed prominently. Slight redundancy in the phrase list could be trimmed, but it's well-structured.

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

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

Given the tool's complexity (two pipelines, six verdicts, error handling), the description covers everything an agent needs: when to use, what happens under the hood, what it returns, and how to interpret ambiguous outcomes. It even explains why it replaces multiple sequential calls. No gaps for correct invocation.

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

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

Schema coverage is 100% for both parameters. The description adds value by explaining tolerance_pct's role in hallucination detection (set 1–2 for strict checking) and noting the default is implied by wording capped at 5. It also provides a concrete example of the claim parameter. This goes beyond 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 clearly states it performs natural-language claim verification with specific trigger phrases ('fact check', 'verify the claim that...'), and explicitly defines its scope: company-financial claims via SEC EDGAR/XBRL fast path, all other claims via grounded pipeline. It distinguishes itself from siblings by naming the exact function and output verdict types.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two routing paths (structured vs grounded) and mentions it replaces 4–6 sequential calls, making it clear this is the go-to tool for claim verification without ambiguity.

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