Edgar

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) indicate the tool is safe and non-destructive. The description adds important behavioral details: it returns per-model score, confidence, signals, and raw_response, and explains that the default model is free while Anthropic requires a BYO key with direct payment. No contradictions.

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 four sentences with no redundant information. It front-loads the primary action and result, then details default vs. paid options, return format, and use cases. Every sentence adds value.

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

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

Given the tool has 4 parameters and no output schema, the description covers the tool's purpose, parameter usage, return structure, and typical use cases. It is thorough enough for an agent to understand when and how to invoke the tool, though it could optionally include an example query.

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?

Input schema has 100% description coverage, but the description adds context beyond the schema, such as the free default model, the role of _apiKey, and how `context` helps disambiguate. This provides additional meaning for parameter usage.

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

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

The description clearly states the action ('Probe one or more LLMs') and the resource ('what they know about a business/brand/product/topic'), and specifies the output ('score visibility (0-100) per model'). It also distinguishes itself from sibling tools like deep_research and scan_competitor_ai_presence by focusing on AI visibility scoring.

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 usage context: it's for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It also explains when to use the Anthropic model (requires _apiKey) and notes the free default. However, it does not explicitly exclude cases where this tool should not be used or directly compare it to similar siblings.

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

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses the routing behavior, argument filling, and stable citation URIs in the return value. There is no contradiction with the annotations, though it does not describe failure modes or rate limits.

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 'PREFER OVER WEB SEARCH' and then efficiently covers domains, trigger phrases, examples, and return behavior. It is slightly repetitive in saying 'even if web search could also answer it' twice, but the length is warranted by the broad routing scope.

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 router tool with no output schema, the description provides enough for an agent to know what input to provide and what to expect back: a structured answer with citations from one of 5,798 tools across 1,517 sources. The only notable gap is the lack of any mention of the closely named sibling variants, which would help complete the decision 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?

Schema description coverage is 100%, and the main question property already documents that it accepts natural language with aliases query, q, prompt, text, input. The description contributes no parameter-specific semantics beyond saying the tool routes 'the question', which is acceptable when 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 names a clear verb and resource: it routes natural-language questions to one of 5,798 tools, fills arguments, and returns answers with pipeworx:// citation URIs. It is sharply distinct from web search, but it does not differentiate this tool from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, so it misses the top score.

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 is explicit about when to prefer this tool, giving domain examples (SEC, FDA, FRED/BLS, weather, etc.), trigger phrases ('what is', 'look up', 'get the latest'), and sample questions. It even says to use it even when web search could answer, but it gives no explicit when-not-to-use guidance or pointers to alternative siblings.

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, it discloses that this is an experimental edge, that candidate routing improvements are enabled live only while under test, that the last candidate was retired on a specific date, and that it currently matches ask_pipeworx exactly. It also explicitly says it falls back to nothing and is a full working router.

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

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

The description is front-loaded with the tool's identity and experimental nature, then gives current state and usage context. It is slightly longer than strictly necessary, but each sentence contributes useful caveats about routing behavior.

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

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

For a beta router with no output schema, it conveys current behavior, relationship to the stable router, argument compatibility, experimental status, and failure mode. An agent can decide when to call it and what to expect, especially because the response shape is defined by parity with ask_pipeworx.

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 each parameter is already described as an alias for question. The description adds only the claim that arguments match ask_pipeworx, but provides no additional syntax, format, or semantic detail beyond what the schema already gives.

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?

Opening sentence states it is the beta version of ask_pipeworx with an identical universal router across 5,798 tools, same arguments, and same response shape, plus candidate routing improvements. This makes the action and resource clear and distinguishes it from ask_pipeworx and ask_pipeworx_grounded.

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 use it like ask_pipeworx when wanting the newest routing, and clarifies that no candidate is currently active so behavior matches stable. It does not explicitly state a 'do not use' condition for cases requiring guaranteed stable behavior, but the experimental framing makes that largely inferable.

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?

It discloses key behaviors beyond the readOnlyHint: the tool extracts answers exclusively from tool results, returns evidence as a verbatim quote, and refuses rather than fabricating when data is insufficient. The explicit refusal reason enum and output shape give the agent accurate expectations for failure modes.

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 front-loads the core purpose, explains behavior, gives the output shape and refusal reasons, and closes with usage guidance and cost tradeoff. It is structured to quickly inform an agent without padding.

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 there is no output schema, the description compensates by fully describing the success and refusal response shapes. It also explains the routing mechanism, grounding behavior, cost, and when to prefer the sibling tool, making it complete for both selection and 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 description coverage is 100%, so the input schema already fully documents the question parameter and its aliases. The description does not add parameter-specific detail, but none is needed; 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 clearly identifies a specific verb and resource: a grounded, hallucination-resistant answer mode that extracts answers only from tool results. It distinguishes itself from ask_pipeworx by emphasizing verified extraction and explicit refusal behavior, so the agent can tell them apart.

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 the tool: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts, with concrete domains listed. It also names ask_pipeworx as the alternative for casual lookups and notes the extra LLM call cost, providing clear 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?

The description extensively discloses behavioral traits beyond annotations: resolver contract with confidence levels, parent event extractor, news fields with fallback handling, safety mechanisms for low-confidence and closed markets, liquidity warnings, and resolution-rule risk. Annotations indicate read-only, open-world, idempotent, and non-destructive behavior, which aligns with the description. No contradictions.

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

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

The description is lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Key information is front-loaded, and each section conveys necessary details without redundancy. While verbose, it remains focused and informative.

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 provides comprehensive coverage of response shapes, edge cases, safety considerations, and resolution rules. It fully equips an AI agent to understand what the tool returns and how to handle various scenarios, making it contextually complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant meaning: it clarifies that 'market' accepts multiple formats, explains the 'depth' enum values, and details the 'include_raw' parameter's trade-offs. This goes beyond the schema's description, earning a higher score.

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 defines the tool's purpose: researching Polymarket bets by pulling relevant Pipeworx data. It specifies the input formats (slug, URL, question text) and describes the process of resolving, classifying, and fanning out to data packs. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It includes examples of classifiers and fan-outs, giving context for when to use the tool. However, it does not explicitly state when not to use it or suggest specific alternatives among siblings, which would improve the score.

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

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

Annotations declare read-only, idempotent, non-destructive. Description adds details on parallel call, sorted results, fiscal year handling, and return of citation URIs, enhancing transparency 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?

Description is slightly verbose but well-structured with front-loaded query patterns and clear breakdown. Every sentence adds value, though minor redundancy exists.

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?

Fully covers return data (sorted, paired, URIs), both entity types, and edge cases (off-calendar fiscal years). Without output schema, description provides sufficient context for agent to predict results.

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

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

Schema descriptions are present (100% coverage), but description adds significant meaning: explains what data is pulled for each type (revenue, debt, etc.) and gives specific examples for values (tickers vs drug names).

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 clearly states verb (compare) and resource (entities), distinguishes from siblings by explicitly preferring over sequential lookups and noting it replaces 8-15 calls.

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 advises to use over sequential single-pack lookups for comparisons. Provides clear context for when to use (comparing 2-5 companies or drugs). Could mention specific sibling tools as alternatives, but guidance is strong.

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 safe read-only, open-world, idempotent behavior, and the description adds rich non-contradictory context: decomposition into facets, parallel routing, findings-packet fields, explicit gaps rather than invented answers, citation_uri resolvability guarantees, contradiction scanning, semantic excerpting, and latency expectations. This goes well beyond the hint 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 information-dense and front-loaded with prerequisites and routing guidance. Almost every sentence earns its place, though a little tightening is possible since some depth semantics repeat the schema and 'use ask_pipeworx instead' appears twice.

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 unusually complete for a tool with no output schema: it covers prerequisites, scope, decomposition behavior, output packet fields, gap handling, citation fetchability, contradictions, excerpting, and time expectations. An agent has enough to decide when to call it and what to expect back.

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

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

Schema coverage is 100%, so the schema carries the baseline burden; the description still adds value by giving example multi-part questions, clarifying that 'thorough' requires a paid plan, and stating latency expectations tied to depth. That is more than the input schema provides, even though much enum semantics are already present in 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 states a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly contrasts with open-web search and with ask_pipeworx, so an agent can distinguish this tool from siblings 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?

It gives explicit when-to-use conditions (broad/multi-part questions over structured data) and explicit alternatives: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead'. It also flags the paid-plan requirement for depth:'thorough', which is exactly the routing information an agent needs.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by stating results are 'ready to call directly, no second schema lookup needed' and describing the output format, with no contradictions.

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 concise: first sentence states function, second lists domains, third explains output, fourth gives usage guidance. No wasted words.

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

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

Despite no output schema, the description fully explains the return format (top-N tools with names, descriptions, full schemas) and mentions the limit parameter. Complete for a discovery 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% with all parameters described. The description adds context about multiple aliases but not deeper semantics beyond schema. 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 finds tools by describing data or task, lists many domains, and contrasts with sibling tools that are specific data tools. It is a specific verb+resource with sibling differentiation.

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

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

Explicitly says 'Call this FIRST when you have many tools available' and 'Use when you need to browse, search, look up, or discover what tools exist for: ...' providing clear when-to-use guidance and context.

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

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

Annotations already declare read-only and idempotent behavior, but the description adds substantial detail: results are sorted with currently-listed peers first, unlisted filers appear with ticker:null, the default form_type is '10-K', and the source is SEC EDGAR browse-edgar. It also discloses that SIC buckets include delisted/defunct filers, managing expectations 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 well-structured: purpose is front-loaded, followed by usage guidance, parameter behavior, and caveats. Every sentence adds information, though the density makes it slightly heavier than the leanest possible 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?

With no output schema, the description compensates by specifying return fields (CIK, ticker, company_name), ordering behavior, and how unlisted registrants are represented. It also covers defaults, source, and limitations, so an agent has everything needed to 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it clarifies that sic and ticker_or_cik are mutually exclusive alternatives and explains the ticker_or_cik lookup flow (resolve SIC first, then find peers). It also surfaces the default form_type behavior and the exclude_self default, which adds value beyond the schema's individual 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 opens with a specific verb and resource: 'AUTHORITATIVE peer / competitor lookup: find every SEC filer classified under one SIC.' It clearly distinguishes this from the many sibling EDGAR tools by framing it as the peer/competitor lookup, not a filings, facts, or holdings 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?

It explicitly states when to prefer this tool over web search, with concrete example queries like 'who are $COMPANY's public competitors/peers'. It also explains the two invocation modes (direct SIC vs ticker/CIK resolution) and adds a caution that SIC is a broad starting point, not a precise competitor list.

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, idempotent), the description discloses critical behavioral traits: Q4 rows are derived (FY minus Q1-Q3, marked derived:true), the tool resolves the appropriate XBRL tag per filer, and the `latest` field semantics (newest 10-Q when more recent than last 10-K). These details are not evident from annotations or schema and significantly affect how results should be interpreted.

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, with each sentence adding critical information: source authority, input flexibility, return format, derived Q4 caveat, latest field usage, and explicit use cases. No filler or repetition. The key details are front-loaded with the tool's purpose, and the formatting (caps for emphasis, backticks for fields) aids scannability.

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

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

Given the complexity of financial data (fiscal periods, derived values, tag resolution), the description covers all necessary context for an agent to use the tool correctly. It explains the default return behavior, the `latest` field, and how to match historical periods. With an output schema also present, the description is complete without needing to repeat return structures.

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 provides 100% coverage for parameters, including the ticker/CIK distinction and metric examples. The description adds valuable semantic context by explaining that the concept parameter is a friendly name that the tool maps to the correct XBRL tag (e.g., post-ASC-606 differences) and lists common metric examples. This enriches the schema's basic 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 immediately states the tool's core function: 'AUTHORITATIVE historical financials for any US public company.' It specifies the source (SEC XBRL filings) and the accepted inputs (ticker or CIK plus metric name), and clearly scopes the output to annual and quarterly values. This is a specific verb+resource+scope that distinguishes it from vague or generic tools, even without naming 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 explicit usage guidance with concrete examples: 'Use for "what was AAPL's revenue in 2024", "NVDA's latest cash position", "show me long-term debt trend"'. It also differentiates when to use `latest` versus `values` (point-in-time metrics vs. historical matching) and explains the derived Q4 behavior. This is clear when-to-use advice that goes beyond simple context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial context beyond this: the response leads with latest_annual, retired concepts are flagged as stale, the payload is large, and data is the official SEC-filed numbers. 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 front-loaded with the core purpose and distinguishes the tool from siblings immediately. Each subsequent sentence adds useful context (latest_annual behavior, stale flags, large payload, usage pattern), though the example concept list is somewhat verbose.

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

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

With an output schema present and the single input parameter fully documented, the description supplies all needed decision-making context: when to use, when not to, payload size, stale-concept handling, and the recommended narrow-down workflow. 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 coverage for the single parameter is 100%, including accepted ticker/CIK formats and auto-resolution. The description only mentions 'by CIK' without adding format, syntax, or example details, so 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 clearly states it returns a full XBRL fundamentals dump for a US public company, listing the resource and output type. It explicitly contrasts with edgar_company_concept for one-metric queries, distinguishing itself from the most relevant sibling.

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 'Use when you need the complete fundamental picture vs. one metric' and names the alternative tool edgar_company_concept. It also provides workflow guidance: use once to discover concepts, then narrow to edgar_company_concept for follow-ups.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds what the tool returns (filing dates, form types, accession numbers, document links), which is not in annotations. No contradictions; the description enhances transparency.

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 well-structured sentences plus a concise list of form type explanations. Front-loaded with the main purpose. Every sentence adds value; no fluff.

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

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

Covers all necessary context: what the tool does, input parameters with examples, acceptable values for form_type with explanations, return fields, and references to related tools for other needs. Annotations cover safety; description fills remaining gaps.

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

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

Input schema covers all 3 parameters with descriptions (100% coverage). The description adds meaning beyond schema by explaining form type values (e.g., '10-K' is annual report) and providing usage examples. This enriches the schema information, justifying above baseline.

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

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

The description clearly states the verb (list), resource (SEC filings), and scope (specific US public company). It distinguishes from sibling tools by mentioning alternatives for other use cases (edgar_company_concept, edgar_company_facts, sec_8k_recent). The term 'AUTHORITATIVE' reinforces its unique role.

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 (e.g., 'what did $TICKER recently file') and when not to use (e.g., financial metrics use edgar_company_concept). It also recommends a specific sibling (sec_8k_recent) for severity-classified 8-Ks, providing clear decision 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, destructiveHint=false, so safety is established. The description adds behavioral context: it returns 'every document in the filing folder' with specific fields, truncates primary text to ~40k chars, and auto-resolves ticker to CIK. 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 moderately long but well-organized: starts with core purpose, then parameter explanations, then examples. Every sentence adds value. However, it could be slightly more compact by merging some details (e.g., examples are repeated). Still, it is efficient for the amount of information conveyed.

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 has 5 optional parameters, no output schema, and multiple use cases, the description covers all needed context: what is returned (documents with details, form type, date, index page), the two invocation modes, primary text option and its limitation, and the alternative for full text. No 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 has 5 parameters, all with descriptions (100% coverage). The description adds value beyond schema by providing examples, explaining auto-resolution of ticker, clarifying default for include_primary_text, and directing to edgar_filing_text for full text. This extra guidance improves usability.

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 retrieves documents from a single SEC filing by accession number, listing them with details. It distinguishes from sibling tools like edgar_filing_text (for full text) and edgar_company_filings (for list of filings). Examples show both usage modes (by accession or ticker+form_type), providing specific verb+resource.

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 specifies when to use: 'Use to list a 10-K / 10-Q / 8-K's exhibits, retrieve filing contents/attachments, or fetch the text of a filing.' It also explicitly suggests an alternative: 'For the FULL, pageable document text... use edgar_filing_text instead.' While not exhaustive about exclusions, this covers key decision points.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses detailed behavioral traits: HTML stripping, paging via offset/max_chars with next_offset, truncation limits, raw_truncated for very large filings, and the section fallback behavior. 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 every sentence contributes essential information. It's front-loaded with the core purpose, then expands on modes, paging, and alternatives. The structure flows logically from what → how → when, with no redundancy. Given the tool's complexity (7 params, paging, truncation), the length is justified.

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 no output schema, the description fully compensates by explaining return fields (truncated, next_offset, raw_truncated, section_found). It addresses all complexity: two ways to specify the filing, paging mechanism, truncation caveats, section location, and distinguishes from sibling tools. Nothing major is left ambiguous.

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 describes all 7 parameters with 100% coverage, but the description adds crucial context: explains how offset/max_chars work together for paging, defines section enum values, warns about ticker correctness (using example of wrong ticker leading to different company), and clarifies form_type usage for auto-resolution. This significantly enhances schema 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 the tool returns the authoritative full text of a SEC filing's primary document as plaintext, explicitly distinguishing it from sibling tools like edgar_filing_documents (list of documents) and edgar_company_concept (structured numbers). It also names specific use cases (going-concern language, ATM facilities, etc.), making 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?

Provides explicit guidance on when to use this tool versus alternatives (e.g., "For the list of documents/exhibits in a filing use edgar_filing_documents; for structured financial numbers use edgar_company_concept"). Also explains two invocation modes (with accession or auto-resolve via ticker+form_type) and warns about ticker accuracy, giving clear context for correct 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 indicate read-only, idempotent, non-destructive. Description adds data delay (30-60 days), coverage of US-registered funds, and notes that unit investment trusts don't file N-PORT. 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?

Dense yet structured: starts with authoritative tone, then usage, output format, examples, distinction from sibling, caveats. Every sentence adds value. No fluff.

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

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

Given no output schema, the description defines return contents (net assets, holdings count, top positions with name, CUSIP, value, weight). Covers exceptions (unit investment trusts) and delay. Could specify more about pagination or full output structure, but sufficient for confident use.

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 description adds critical nuance: 'Pass the FUND's ticker' and clarifies fund vs company tickers, preventing misuse. The description implicitly explains the limit parameter via 'top positions by weight'. Adds meaning beyond schema.

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

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

The description clearly states the tool returns portfolio holdings of US ETFs/mutual funds from SEC Form N-PORT, specifying 'what the fund actually owns'. It distinguishes from the sibling tool edgar_institutional_holdings (13F).

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 to pass fund ticker (e.g., 'ARKK'), explains limit parameter. Provides use cases ('what does ARKK hold') and explicit 'when not to use' for legacy ETFs like SPY, suggesting alternatives (IVV/VOO). Distinguishes from edgar_institutional_holdings.

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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds behavioral context beyond annotations by explaining that the tool parses filings into structured transactions, detailing transaction codes and their significance (e.g., 'P' as strongest conviction signal). It does not contradict 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 moderately concise for the amount of information conveyed. It is well-structured, starting with the main purpose and return format, then usage examples, transaction code explanations, and a sibling pointer. A slight reduction in redundant phrasing could improve conciseness, but overall it is 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?

Despite lacking an output schema, the description comprehensively explains the return structure: reporting owner with role, transaction code, shares, price per share, acquired/disposed, and shares owned after. It covers all essential aspects for using the tool, including parameter examples with realistic values (TSLA, CIK 1318605). The tool's complexity is well-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?

Input schema has 100% coverage with descriptions for all three parameters. The description adds semantic value by explaining how to use 'ticker_or_cik' (pass 'TSLA' or CIK), clarifying that 'include_derivatives' controls inclusion of options/RSU transactions, and introducing transaction code semantics (P, S, A, etc.) beyond the schema.

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

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

The description clearly states it provides authoritative insider trading activity from SEC Forms 3/4/5, specifying what data is returned (who, shares, price, holdings). It distinguishes itself from the sibling tool 'edgar_company_filings' by directing users there for raw filing lists, thus clearly differentiating 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 explicitly lists use cases ('insider buying at $TICKER', 'did executives sell recently', 'latest Form 4 activity') and provides guidance on interpreting transaction codes (e.g., 'P=open-market purchase' as strongest signal vs 'A=award' as routine comp). It also advises on when to use the sibling tool, giving clear contextual 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 and idempotentHint, but the description adds critical behavioral context: the 13F covers only US long equity + options, values differ by filing year, and put/call rows require careful interpretation (notional vs premium, bearish bets). 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 includes examples and notes in a structured way. It is longer than necessary but every sentence adds value; it could be slightly more concise but remains 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?

Despite no output schema, the description thoroughly explains what is returned (holdings aggregated by issuer, value in USD, shares, % portfolio, report period, and fields like put_call, direction, etc.) and provides crucial interpretation guidance. It is complete for a complex financial data 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% and both parameters are described clearly in the schema. The description essentially restates the schema for 'ticker_or_cik' and 'limit' without adding new meaning. 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 clearly states the tool returns 'stock portfolio of a large institutional investor (SEC Form 13F-HR)' with specific details like share counts and position values. It distinguishes from sibling tools by specifying the SEC form and the manager-level focus, and it provides concrete usage examples like 'what does Berkshire own'.

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 use cases ('Use for...') and mentions limitations (covers US long equity only, excludes shorts/cash, filing delay). It advises on correct interpretation of put/call rows. However, it does not explicitly contrast with the sibling 'edgar_fund_holdings' tool, which may overlap.

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 meaningful behavioral context beyond those: it explains the source is SEC's standardized Financial Report rendering of the 10-K/10-Q note, that results carry citations, that non-disclosure and non-standard layouts surface as explicit statuses, and that there is a fallback tool. This goes well beyond what annotations convey.

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

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

The description is dense but every sentence earns its place: purpose, sibling differentiation, source methodology, parameter guidance, output citation guarantee, and failure-mode behavior. It front-loads the core purpose and then builds outward 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?

Given the tool's complexity, 5 parameters, and no output schema, the description is remarkably complete. It explains what data is returned, what citations accompany results, why results may be absent, how failures are reported, and what to do as a fallback. An agent has enough context 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?

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds helpful context for product_filter by explaining it matches against the dimension breadcrumb and controls whether the whole table or one product is returned, but this mostly reinforces the schema rather than adding substantial new 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?

The description names a precise verb-resource pair ('product-level or segment-level revenue as structured data') with concrete examples ('how much revenue did Keytruda generate', 'AAPL revenue by product line'). It explicitly contrasts itself with sibling tools edgar_company_concept and edgar_company_facts, making the tool's unique niche 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 clearly states when to use this tool: when dimensional product/segment breakdown is needed, because the regular XBRL tools cannot see dimensional tags. It also gives a fallback path to edgar_filing_text when the parser can't read a non-standard layout, and explains failure conditions rather than assuming silent success.

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?

Description adds behavioral details beyond annotations: cheap, no rate limit concerns, return structure including alternatives for name matches. Annotations already declare read-only, idempotent, not destructive, and description is consistent.

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 compact, every sentence adds value. Core purpose is front-loaded with examples, followed by usage guidance and return info. No redundancy.

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

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

For a simple single-parameter tool with good annotations and an output schema, the description covers purpose, usage, relation to siblings, return structure, and cost/performance. Complete for effective agent usage.

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 already documents that the parameter accepts ticker or company name. Description reinforces this but does not add significant new semantic information beyond the schema.

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

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

The description clearly states it resolves a ticker or company name to the SEC's CIK identifier. It distinguishes itself from sibling tools by noting it is required by other SEC tools and that those tools can accept tickers/names directly.

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 to call this first when needing to use other SEC-keyed tools, and only use explicitly when wanting the CIK as data. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context beyond that: it fans out across multiple sources, soft-fails on USPTO until reactivated, returns sources_used/sources_failed so empty sections are meaningful, resolves names via SEC EDGAR, and returns resolved:false with notes for private companies. This is exactly the kind of hidden behavior an agent needs to know before calling.

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: trigger phrases first, then the core value proposition, then source list and output sections, then input semantics and edge cases. Every sentence carries information needed for correct invocation. It's longer than many tool descriptions, but the complexity of the tool justifies it; there is no filler or repetition. A small deduction because the length, while earned, could be trimmed slightly by moving some output-section detail into a more compact structure.

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 2 simple parameters, no output schema, and a complex fan-out behavior, this description is remarkably complete. It covers input formats, resolution behavior, expected empty results (FDA small-molecule), failure semantics (sources_failed, soft-fail), and the return structure in detail. An agent can confidently decide whether to call it and what to do with the result without needing any additional documentation.

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 both parameters in detail. The description adds value by clarifying that type accepts 'company' or 'ticker' interchangeably and both take the same value shapes, which is a non-obvious semantic that would otherwise be ambiguous. It also gives concrete examples for value (AAPL, 0000320193, Moderna) and explains the name-resolution behavior. The only minor gap: it doesn't enumerate every possible output field, but the output format is already thoroughly described in the main description.

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 triggers ("Tell me about X", "research Acme", "brief me on Tesla") and then names the exact resource — a full cross-source profile of a US public company — pulled in one parallel call. It explicitly lists the data sources (SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, GDELT→GNews, GLEIF) and the output sections, which is far more specific than just saying 'entity profile'. It also distinguishes itself from sibling tools like edgar_company_filings or deep_research by framing itself as the holistic aggregation tool to use instead of chaining single-pack lookups.

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 says ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view, which is an explicit usage directive with a clear alternative. It also enumerates accepted input shapes (ticker, zero-padded CIK, or company name) and states the expected behavior for private companies (resolved:false with notes), telling the agent when this tool is not appropriate. The schema and description together leave little ambiguity about when to invoke this tool versus its siblings.

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?

Even though annotations already declare readOnly=true and destructive=false, the description adds substantial behavioral detail: results carry provenance (accession number, filing date, exhibit URL), the status distinguishes 'no Exhibit 21' from lookup failure, and the data comes directly from SEC filings. These details meaningfully shape the agent's expectations 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 core purpose is front-loaded in the first sentence, and later sentences each add meaningful context: example, filter usage, provenance, edge cases, and coverage limitations. It is fairly long and dense, but for a financial-domain tool with legal specifics, the detail earns its place without being bloated.

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

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

Given there is no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: it describes the subsidiary list, jurisdiction of incorporation, provenance fields, name filtering, absence-of-data handling, and coverage gaps. An agent has enough context to call this tool correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value. It clarifies that ticker_or_cik is specifically the PARENT company, explains the name_filter use case as a quick membership check, and describes the source and structure of the data behind the parameters. This exceeds mere schema repetition.

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, specific definition: 'the REVERSE of sponsor_to_filer' that lists a parent company's subsidiaries from Exhibit 21 of its 10-K. It names the exact SEC source and clearly differentiates itself from the sibling sponsor_to_filer, so an agent can select it unambiguously.

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 this tool instead of sponsor_to_filer: instead of making ~10 calls guessing candidate names and confirming each, call this once to get the full subsidiary list. It also documents exclusions (foreign private issuers / 20-F filers not yet covered) and how absence of Exhibit 21 is handled, giving the agent clear decision 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?

The description's 'Delete' aligns with annotations (destructiveHint=true) and adds context about clearing sensitive data, which goes beyond what annotations provide. 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 concise sentences that front-load the core action. Every sentence adds value with no redundancy.

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

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

For a simple delete operation with one parameter and no output schema, the description completely covers the tool's purpose, usage context, and relationships with sibling tools.

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 does not add additional meaning beyond the schema's 'Memory key to delete'. Baseline 3 is appropriate as the schema already fully documents the parameter.

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

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

The description explicitly states 'Delete a previously stored memory by key', which is a specific verb-resource combination. It distinguishes from sibling tools 'remember' and 'recall' by focusing on deletion.

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 usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with related tools, giving explicit guidance on when to use this tool vs alternatives.

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

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

Annotations already declare safe, read-only, idempotent behavior. Description adds value by detailing the process: fetches the page, extracts title/description/key links, and produces standard llms.txt markdown. No contradictions.

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

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

The description is concise (3 sentences) and front-loaded with the action and purpose. Every sentence serves a purpose: defining the output, explaining the process, and listing use cases. No unnecessary words.

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

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

For a simple tool with two parameters, no output schema, and comprehensive annotations, the description is complete. It covers what the tool does, how it works, and when to use it, leaving no gaps for the agent.

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

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

Schema coverage is 100% with clear descriptions for url and max_links. The description mentions fetching the page and link count, but does not add substantial new meaning beyond the schema. 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's purpose: generating a production-ready llms.txt file for any URL, with specific verb (generate) and resource (llms.txt from URL). It distinguishes itself from sibling tools which focus on research, validation, or other tasks.

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

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

Provides explicit use cases (client site indexing, personal project drafting, competitor auditing) and implies when to use. Lacks explicit 'when not to use' or alternatives, but the context is clear given sibling diversity.

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 convey read-only and idempotent nature. The description adds value by listing the exact fields returned and the optional 'include_inactive' behavior, which goes 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 only two sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words.

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

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

The tool is simple with one optional parameter and no output schema. The description fully covers purpose, returned fields, and usage context. Nothing is missing.

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

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

Schema coverage is 100%, and the single parameter is described in schema. The description does not add extra meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifying verb, resource, and scope. It distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing.

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: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear usage context, though it doesn't detail when not to use.

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 are all false and offer no safety context, so the description carries full burden. It discloses rate-limiting (5/day), claim_token behavior for anonymous filing, follow-up usage, daily digest cadence, and cost/quota implications — far beyond baseline.

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 adds practical information (scope, exclusions, token flow, limits). It is front-loaded with the core purpose and well-organized, though slightly verbose.

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

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

For a tool with 4 params, nested object, no output schema, and neutral annotations, the description covers all necessary context: purpose, when/when-not, behavioral traits, parameter usage nuances, rate limits, and response handling. It is a fully self-contained usage guide.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token workflow ('Filing without an account returns a claim_token; pass it back later…') and gives guidance for the message param ('describe in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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 'Tell the Pipeworx team something is broken, missing, or needs to exist' — a specific verb+resource+scope statement. It distinguishes from sibling tools by explicitly excluding feedback for other MCP servers and focuses on Pipeworx tools/packs.

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 (bug, feature/data_gap, praise) and when not to use (other vendor's connectors), naming the alternative action ('file it with that server instead'). Also clarifies how to identify Pipeworx tools, giving clear selection 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?

Annotations already declare safe, read-only, idempotent behavior. The description adds valuable context: data source ('CF analytics-engine'), no PII, and caching duration ('5min-1h'). This goes 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?

Description is succinct, front-loaded with the key purpose, and uses bullet-like formatting for use cases. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one optional param, read-only, no output schema), the description fully covers purpose, use cases, data source, privacy, and caching. No gaps for agent 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% with the only parameter 'window' fully described. The description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances selection guidance.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It uses a specific verb ('returns') and resource ('trending on Pipeworx'), effectively distinguishing from siblings like 'discover_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?

Three explicit use cases are provided: discovering hot data sources, confirming canonical choice, and seeing alignment. However, no alternatives or when-not-to-use scenarios are mentioned, leaving room for ambiguity with similar tools.

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. Description adds rich behavioral details: scanning logic, partition filter (placeholder filtering), similarity threshold (Jaccard ≥0.30), fill check against live CLOB depth, and response structure. No contradictions.

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 well-structured with front-loaded purpose and mode distinctions. It is dense but every sentence adds useful information. Slightly verbose but not wasteful; clear organization with line breaks for key sections.

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 explains response structure (opportunities array, partition_check fields, fill check results). Covers all modes, constraints, and edge cases (e.g., placeholders, similarity filter). Complete for a complex arbitrage 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% with descriptions for event and topic. Description adds valuable context: event accepts slugs or URLs, topic is a seed question for cross-event scan. Provides examples and clarifies behavior beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between no-args, event, and topic modes, and is distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicit instructions for when to use each parameter: no args for trending scan, event for specific market, topic for cross-event scan. Recommends event for specific markets and warns when not to trade based on fill check. References sibling tool polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds significant behavioral context: caching for 1h at KV level keyed on knobs, model family details (e.g., crypto_price using lognormal barrier from FRED log-returns), and diagnostics to explain empty segments. 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 comprehensive but verbose. It is well-structured with segments and knobs, but could be more concise. Some details (e.g., specific α values for sports) are informative but add length.

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), the description is thorough: it explains response structure (by_segment, _diagnostics), edge calculation, tradeable-edge knobs, and caching behavior.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning beyond schema, e.g., explaining that min_edge_pp is net of slippage, and slippage_pp subtracts from raw edge before ranking and Kelly sizing.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It differentiates from sibling tools like polymarket_arbitrage by focusing on discovering opportunities without paging hundreds of markets.

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 it's built for 'what should I bet on today' and provides guidance on using knobs like min_liquidity and max_spread_pp. It also explains when the edge may already be in the price. However, it doesn't explicitly compare to siblings or state when not to use.

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 it as read-only, idempotent, and non-destructive. The description adds extensive behavioral detail: it reads from snapshots, uses daily closes, computes trends and decay, and explains response structure. No contradictions.

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 fairly long but well-organized: purpose, parameters, response format with examples, and limitations. Every sentence adds value, though some technical jargon could be simplified. Front-loading is good.

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 comprehensively explains return values (tracked, expired, snapshot_dates) and their fields. It also covers limits and edge cases (gaps in snapshots). Complete for a tool with 2 optional params.

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

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

Schema coverage is 100% with clear descriptions for both parameters (days, window). The description adds default values and clamps but does not significantly extend understanding beyond schema. 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's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge age and trend, distinguishing it from sibling tools like polymarket_edges.

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 context by contrasting fresh vs. old edges, implying when to use this tool for historical insight. It also notes limits like 60-day TTL, but does not explicitly compare to alternatives or state when not to use.

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 well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing the order-book walk, return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.), and basket-specific outputs like thin_legs, forced_directional_risk. It warns about real-world pitfalls like partial basket fills and uncapturable theoretical overround.

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 relatively long (~150 words) but well-structured with CAPS headings and dashes. Every sentence serves a purpose given the tool's complexity (two modes, multiple return fields, warnings). Slightly verbose but justified.

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 comprehensively documents return fields for both modes, including verdict, profit_usd, per-leg fill details, thin_legs, max_clean_notional_usd, and forced_directional_risk. It covers edge cases like partial fills and has no omissions 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?

With 100% schema description coverage, the description still adds significant value by explaining parameter interactions (market vs event required, side defaults, size_usd interpretation as spend vs target proceeds vs settlement notional). It provides mode-specific semantics and clamping 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 clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by instructing 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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

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

The description provides explicit guidance on when to use the tool: before acting on arbitrage signals or trades above ~$500. It explains the risks of partial fills converting an arb into an unhedged directional position. It clearly separates single-market and basket modes with required parameters and side handling.

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 it supplements, disclosing intricate behavioral details: compatibility codes, temporal_alignment_unknown semantics (explicitly 'NOT the same as confirmed-aligned'), gross vs net spread interpretation, skipping of unknown legs into unclassified sets, and the fee differential (Kalshi charges, Polymarket does not, not modeled). It also explains that pre-mapped topics are not guaranteed tradeable. No contradiction with annotations 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 a dense, multi-sentence monolith with SHOUTED section markers and numerous codes, more than 300 words. Although every sentence carries information, the lack of bullet points or clear paragraph separation makes it hard for an agent to parse quickly. It front-loads the core purpose but then buries key safety fields in a wall of text.

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

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

There is no output schema, so the description must explain return values, and it does: raw probabilities, top_spreads_pp, compatibility fields, skipped counts, and temporal_alignment object. It covers edge cases like null temporal_alignment meaning not computable, unknown legs never paired, and fee disclosure. For a tool of this complexity with no structured output schema, the description is extremely thorough.

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?

Input schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful semantics by explaining how the three parameters interact in two modes, clarifying that explicit ticker/slug override the topic-mapped side, and noting that both modes run the identical overlap matcher. This goes 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 first sentence immediately states the core function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This is a specific verb (spread/compute) and resource pair, and the name and description clearly identify it as a cross-venue analysis tool, distinct from siblings like polymarket_arbitrage or polymarket_edges. The description even clarifies the intended use case (same resolving question) and warns against over-use of pre-mapped topics.

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 explains two usage modes (topic shortcuts vs explicit ticker/slug pairing) and gives concrete examples of topic names. It also provides guidance on when to expect real signals ('when bet shapes are equivalent') and warns that most pre-mapped topics currently return compatibility warnings. However, it does not explicitly name a sibling tool to use instead, nor does it state when not to use this tool 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 and idempotentHint=true, so description need not repeat. It adds valuable context about scoping to user identifier, which is 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?

Three sentences, no redundancy. Front-loaded with main purpose and immediately useful examples. Every sentence adds value.

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

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

Though there is no output schema, the description implies the return is a value or list of keys. For a simple retrieval tool, this is nearly complete; could mention behavior on missing key but not critical.

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 the single parameter 'key'. Description adds meaning by stating omitting the key lists all keys, which is not in 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 retrieves a value by key or lists all keys, with specific examples like 'user's target ticker' and explicit pairing with 'remember' and 'forget'. It distinguishes from 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?

Description explains when to use (look up context stored earlier, avoid re-deriving) and how it pairs with remember/forget. It does not explicitly exclude scenarios, but the guidance is clear for the common case.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context: mark_read flags events as read, polls work, and the feed is shared with a GET endpoint. 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 single paragraph that efficiently conveys all necessary information without redundancy. Could be slightly more structured (e.g., bullet points for parameters) but remains concise and front-loaded with the main action.

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 specifies return fields (source, citation_uri, raw payload) and explains all key parameters. It covers filtering, pagination (limit), and state management (mark_read, unread_only). Fully adequate for an agent to use 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%, and the description adds meaning beyond the schema: e.g., type example 'sec_8k', since format as ISO timestamp, mark_read effect ('next call only shows newer ones'). This compensates fully for any schema-only limitations.

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 'Pull fired events from your subscription feed' and specifies the return fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on alert events from 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?

The description provides filtering options (type, since), a usage example (mark_read), and mentions the alternative REST endpoint for scripts/dashboards. It lacks explicit comparison to other sibling tools but gives solid guidance on when and how to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destruction. The description adds significant detail: multi-source fan-out, fallback behavior, soft-fail for USPTO, and the structure of the return value (grouped changes, total_changes, citation URIs). No contradictions.

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 relatively long but well-structured with example queries upfront, then details. Every sentence adds value, though it could be slightly tighter. Still earns a 4 for efficient communication.

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 three required parameters and no output schema, the description covers return structure, source behaviors, fallbacks, and error modes (soft-fail). The description is thorough, making the tool well-understood without additional output docs.

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 description adds substantial value: explains date formats for 'since' with examples, recommends '30d' for monitoring, clarifies 'value' accepts ticker or CIK, and notes 'type' is limited to 'company'. This goes well beyond the schema descriptions.

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

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

The description uses specific verbs like 'returns' and 'feed', names the resource 'change feed for a company', and explicitly contrasts with sibling tool 'entity_profile' for static profile. It clearly defines the scope (last N days/weeks/months) and sources.

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

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

Provides explicit when-to-use guidance with example queries and directs to 'entity_profile' for static profiles. The mention of fallback logic (GDELT→GNews) also helps in understanding usage context.

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

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

Adds behavioral context beyond annotations: memory scoped by identifier, persistence for authenticated vs anonymous (24 hours). Annotations already indicate idempotent and non-destructive, but description enriches understanding.

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 efficient sentences, front-loaded with core function, minimal waste. Every sentence serves a purpose.

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 store tool with full schema and clear annotations, the description covers persistence, scope, and pairing with siblings. No gaps.

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

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

Schema has 100% coverage with reasonable descriptions. Description adds example key patterns (e.g., 'subject_property') but not significantly more value. 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 saves data for reuse, specifies the action (save) and resource (key-value pair), and distinguishes from siblings recall and forget. It uses specific verbs and resources.

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 tells when to use ('when you discover something worth carrying forward') and mentions alternatives ('Pair with recall to retrieve later, forget to delete'). Provides clear context.

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

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

Annotations already establish read-only, open-world, idempotent, non-destructive behavior, and the description complements this with genuinely useful behavioral details: identifiers are labelled by source, unresolved identifiers are explicitly listed under `unresolved`, ambiguous instrument matches return `figi_candidates`, and LEI/FIGI enrichment degrades gracefully if upstream sources are unavailable. 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 and dense, but the length is largely justified by the complexity of the tool, and the opening query examples front-load intent effectively. It could be improved with clearer bullet formatting rather than large parenthetical blocks, but there is very little redundant or irrelevant prose.

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 behavior. It covers company identifiers (CIK, ticker, LEI, FIGI), source labelling, `unresolved` fields, ambiguous `figi_candidates`, and the drug return shape (RxCUI, ingredient, brand, citation). Degradation and failure modes are also addressed, making the tool callable with confidence.

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 well beyond the schema: it explains the ISIN-to-LEI mapping, the ticker-implied name search, the fact that non-equity instruments without tickers still resolve, and the critical bond-name caveat to pass only the issuer name. This is far more than the 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 concrete user phrasing and states the core action precisely: it resolves a user-spoken NAME to the canonical/official identifiers that other tools require. It also names the supported entity types (company, drug) and frames itself as a replacement for 2-3 manual lookups, distinguishing it from more specific siblings like edgar_ticker_to_cik or entity_profile.

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 an explicit routing rule: 'Use FIRST whenever you have a name but need an ID.' It also provides type-specific guidance, including how to handle ambiguous matches via `figi_candidates`. It does not spell out when-not-to-use or name alternatives as exclusions, but the primary selection condition is clear enough.

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

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

Beyond annotations (readOnly, idempotent), description details what happens: probes each entity, ranks by score, surfaces most/least recognized, and returns ranked list with score, confidence, signal density. No contradictions.

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, front-loaded with purpose, then mechanism, then use case. No redundant information.

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

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

Given no output schema, description adequately explains return format (ranked list with score, confidence, signal density). The tool's complexity is moderate, and description covers inputs, process, and output sufficiently.

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 with descriptions. Description adds value by noting that first entity is treated as 'subject' for narrative, which is not in schema. This helps agent understand argument ordering.

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 clearly states it compares AI visibility across multiple entities, using ai_visibility_check per entity, and ranks results. This distinguishes it from single-entity tool ai_visibility_check.

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?

Description explicitly mentions competitive AI-marketing audits and gives an example query. It implies usage context but doesn't specify when not to use or list alternatives directly.

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, non-destructive. Description adds critical behavioral insights: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts, and returns summary blocks, advisories, links, and alternatives. This goes well beyond annotation payload.

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 dense but well-structured: front-loads purpose, then usage, then behavioral details. Each sentence earns its place. Slightly long but not unnecessarily so. Could be tightened slightly but remains effective.

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

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

For a composite tool with no output schema, the description fully documents the return structure (summary block, per-advisory detail, links, alternative versions). Paired with 100% schema coverage and complete annotations, an agent has sufficient information 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?

Schema covers both parameters with descriptions (100% coverage). Description adds that scoped packages (e.g., @types/node) are accepted and that version defaults to the latest. This extra context justifies a score above 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?

Clearly states it is a composite check for adding an npm package, fanning across deps.dev and bundlephobia. The verb 'scan' and resource 'dependency' are specific, and the target ecosystem (npm) is explicit. No sibling tool performs this function, so differentiation is inherent.

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

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

Explicitly says when to use: when an agent asks about safety, popularity, size, or cost of adding an npm package. Also states NPM ecosystem only in v1 and mentions alternative for other ecosystems (deps.dev:version directly). Provides clear context for invocation.

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?

Adds significant behavioral context beyond annotations: embeddings model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character limit (200K chars with truncation flag). No contradictions with annotations (readOnly, idempotent, non-destructive).

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 concise sentences, each serving a distinct purpose: purpose, usage, pairing, and technical details. No redundancy, front-loaded with key information.

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

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

Despite no output schema, the description explains what is returned (top-N passages with offsets and scores). Covers pairing, technical constraints, and use cases. Fully adequate for an agent to select and invoke the 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% (all three parameters described in input schema). The description adds minor value: example queries for 'query', maximum char note for 'text', and default limit. Meets baseline but does not significantly enhance beyond schema.

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

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

The description clearly states the tool does 'Semantic search INSIDE a fetched record' with a specific verb-resource pair. It provides examples (SEC 10-K, article) and contrasts with sibling tool 'ask_pipeworx_grounded', effectively distinguishing its role.

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 when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages with offsets). Lacks explicit non-use cases, but pairs well with another tool for a complete workflow.

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 annotations (idempotentHint true, readOnlyHint false), the description discloses key behaviors: auth requirement, persistence requirement, delivery channel constraints, and webhook signature verification. However, the idempotentHint true annotation ambiguously interacts with 'Returns the new subscription id,' as retries might create duplicates—this is not clarified, slightly reducing transparency.

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

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

The description is well-structured: it opens with the core purpose, then covers constraints, types, and delivery channels in a logical order. It is somewhat dense with examples but each sentence serves a purpose. Minor redundancy (e.g., mentioning SMS cap twice) could be trimmed.

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 (3 parameters, nested objects, multiple types) and no output schema, the description covers most critical aspects: types, params examples, delivery options, and what is returned (subscription id and optionally webhook secret). Missing are error scenarios and behavior on duplicate requests, but overall it is contextually sufficient.

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 value by providing concrete examples for each subscription type (e.g., sec_8k with items codes) and explaining the params object structure. This goes beyond the schema's short descriptions, making parameter usage clearer.

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 starts with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It effectively distinguishes from siblings like list_subscriptions (listing) and unsubscribe (deletion) by stating its action of creation.

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 context on when to use the tool: for persistent monitoring with delivery options. It includes prerequisites (OAuth account), types and their filter parameters, and delivery limitations (SMS cap, webhook secret). However, it does not explicitly compare with siblings like list_subscriptions or recent_alerts, leaving some interpretative load on the agent.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds that it returns example questions with tool shapes, explains the behavior for no argument vs topic. No contradictions, and adds value 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 fairly long but well-structured with example queries, purpose, output description, parameter usage, and when to use. Every sentence adds value; could be slightly more concise but not excessive.

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 tool (one optional param, no output schema, rich annotations), the description covers purpose, usage, parameter, and output format adequately. Could specify return structure more precisely, but overall 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%, baseline 3. Description enriches by explaining the topic parameter with examples and that omitting it gives full spread, adding 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 description clearly states the tool returns example questions categorized by topic, with exact tool call shapes. It distinguishes itself as the onboarding entry point, not just a generic suggestion tool, and includes example queries users might type.

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 this FIRST' and describes when to use (when not knowing what Pipeworx can do) and the option to pass a topic to focus. It doesn't explicitly state when not to use, but context 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?

Beyond annotations (readOnlyHint false, destructiveHint false, idempotentHint true), the description adds critical behavioral details: ownership enforcement, deactivation semantics, and availability of historical events via sibling tool. No contradictions.

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, each essential. First sentence states verb, resource, and constraint. Second sentence explains the detailed effect and references a sibling tool. No redundant information.

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

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

Given the tool's simplicity (one parameter, no output schema) and comprehensive annotations, the description fully covers the tool's behavior, constraints, and relationship to sibling tools.

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

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

Schema coverage is 100% with a clear parameter description. The description adds no additional meaning beyond 'by id', but the schema already provides sufficient information. 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 clearly states the action ('Cancel a subscription by id') and the resource, distinguishing it from 'subscribe' and 'list_subscriptions' by specifying the effect (deactivation, not deletion) and 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?

Provides explicit context: when to use (cancel own subscription), ownership enforcement, and what happens (deactivation, not deletion) with a link to 'recent_alerts' for historical events, effectively guiding the agent on when not to use this tool.

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

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

Beyond the annotations (read-only, idempotent, open-world), the description discloses critical behavioral nuances: could_not_verify means the check did not happen and is not evidence for/against, unsupported means no source covers it, and the existence of a verification_error object with stage/detail. It also reveals the two execution paths and that evidence is quoted verbatim.

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 every sentence carries useful information: trigger phrases, routing rules, return structure, and important caller warnings. It is well-structured, front-loading the purpose and then detailing behavior, with no filler or repetition.

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

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

For a complex tool with no output schema, the description covers all key aspects: exact verdicts returned, evidence citation, reasoning, failure modes (could_not_verify vs unsupported), and both processing pipelines. It gives enough detail for an agent to understand what will happen and how to interpret results, making it complete 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?

The schema already fully describes both parameters (100% coverage), so the baseline is 3. The description adds value by explaining tolerance_pct's practical effect: it overrides the tolerance implied by claim wording, and recommends 1–2% for hallucination detection. This supplements the schema without redundancy.

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 defines the tool as fact-checking natural-language claims, with specific verbs like 'verify' and 'validate' and a specified resource ('factual claim'). It distinguishes itself from sibling research tools by listing trigger phrases ('Is it true that…') and noting it replaces 4–6 sequential lookup calls, making its niche obvious.

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 the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and provides concrete natural-language trigger examples. It also gives routing guidance: company-financial claims go through SEC EDGAR/XBRL, while other claims fall through to the grounded pipeline, which effectively communicates when to choose this over alternatives.

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