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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining it returns 'structured answer with stable pipeworx:// citation URIs' and mentions it routes to specific sources like SEC filings, FDA data, etc. It doesn't describe any additional behavioral traits beyond annotations, but the annotations are rich and the description provides useful context.

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

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

The description is relatively concise for its informative load, but could be slightly tighter. It front-loads the key preference statement and usage guidelines, then provides examples and tool comparisons. It's well-structured but a bit long.

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 complex ecosystem (many sibling tools, many sources), the description covers all necessary context: when to use, what it returns, how to step up to alternatives, and concrete examples. No output schema exists, but the description explains return value nature (structured answer with citations).

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter semantics beyond what the schema provides (e.g., it doesn't give examples of question format or length limits). However, the schema itself is made clear by the examples and descriptions.

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

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

The description clearly states it routes questions to a large set of tools and returns structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each.

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 many factual questions, provides concrete examples, and directly tells when to step up to alternative tools (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions).

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

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

The description adds value beyond annotations by explaining that the tool is a full working router (not a fallback), currently matches the stable version, and is used for experimental edge testing. Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior; the description confirms this is a safe, non-mutating query tool and adds the experimental context without contradiction.

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

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

The description is concise and front-loaded: it immediately states the purpose, then clarifies the current state and usage guidance. Every sentence earns its place, with no wasted words. The structure flows logically from identity → current state → usage → 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?

Given the complexity (5,564 tools, experimental routing) and the presence of comprehensive annotations and schema, the description is mostly complete. It explains the beta status, candidate testing, and current equivalence to the stable version. Minor gap: it doesn't explicitly mention the response shape or that no output schema exists, but this is acceptable since the description states the response shape matches ask_pipeworx and the tool is a query router.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter-level details beyond what the schema already provides (it simply references 'same arguments' and 'question'). No new meaning is added, so the score remains at 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 tool is a 'beta version of ask_pipeworx' that serves as an 'identical universal router' with the same tools, arguments, and response shape. It immediately distinguishes itself from the stable version by specifying it includes candidate routing improvements, providing a specific and actionable verb-resource pair.

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: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains the purpose of the beta (comparing results to decide what merges) and clarifies that no candidate is active now, so it currently matches the stable version. This is excellent guidance for tool selection among 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 annotations, the description discloses the return structure with specific fields and refusal reasons, the hallucination-resistant mechanism, the extra LLM call cost, and the fact that it routes across many tools. This adds significant behavioral context that annotations alone do not cover.

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

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

The description is compact, front-loaded with the key purpose, and every sentence provides essential information: purpose, mechanism, return format, usage guidance, and trade-off. No redundant or wasteful 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?

Given the tool's simplicity (single required parameter, no output schema), the description fully covers behavior, return structure, refusal reasons, and usage context. No obvious gaps exist for an AI agent to correctly 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 description coverage is 100%, with all six parameter aliases documented. The description does not add new parameter-level meaning beyond what the schema already states (the question is natural language). Baseline score of 3 is appropriate as the description adds no incremental parameter clarity.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains its unique behavior of extracting answers only from tool results. It distinguishes itself from the sibling `ask_pipeworx` by specifying an extra LLM call cost and use case differences.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' for high-stakes domains, and contrasts with `ask_pipeworx` for casual lookups. Provides clear when-to-use and when-not-to guidance, including specific examples (financial, legal, medical).

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?

Description adds extensive behavior beyond annotations: account requirement, paid tier, time estimates (15-60s, thorough up to 90s), depth mechanics (gap recovery, contradictions), that results include gaps[] and stable citations, semantic excerpting, and that second-hop iteration re-angles unanswered gaps. All consistent with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations.

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

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

Every sentence earns its place. The description is front-loaded with the critical account requirement, then systematically covers use cases, behavior, depth levels, return format, and limitations. While lengthy, the complexity of the tool justifies the length. 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?

Given no output schema, the description thoroughly explains the return findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[]). It covers prerequisites, timing, edge cases (breaking news returns empty gaps), and semantic excerpting. Complete enough for correct tool 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 has 100% coverage but description enriches both parameters. For 'depth', it explains the semantic difference between quick/standard/thorough (facets count, hops, contradictions). For 'question', it clarifies that broad/multi-part natural language is acceptable and that decomposition is the point. Adds significant value beyond the schema.

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

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

The description clearly states the tool does 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources', decomposes questions into facets, and routes to 5,564 tools in parallel. It distinguishes itself from siblings like ask_pipeworx (single lookup) and ask_pipeworx_grounded (different scope). The purpose is precise with a specific verb+resource and clear 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 states when to use: 'broad/multi-part questions over structured data'. Provides when-not: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also guides on depth levels and account requirements. No ambiguity.

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?

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 readOnly and idempotent. Description adds that data is authoritative, from SEC filings, not estimates, and notes large payload. 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?

Two sentences: first packs comprehensive purpose and content, second gives usage guidance. Every sentence adds value, efficiently structured.

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

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

Given output schema exists and annotations cover safety, description is complete. It mentions large payload and workflow recommendation, providing sufficient context for agent 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?

Only one parameter 'cik' with 100% schema coverage. Schema already describes it as accepting ticker or CIK. Description does not add extra semantics beyond reinforcing CIK-based lookup. 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 returns a full XBRL fundamentals dump for a US public company by CIK, listing many example metrics. It distinguishes from sibling tool edgar_company_concept by contrasting the scope.

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 you need the complete fundamental picture vs. one metric' and names the alternative tool edgar_company_concept. Also suggests using once to discover concepts then narrow to that sibling.

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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which already signal safe, read-only behavior. The description adds critical behavioral details: paging mechanism (max_chars, offset, next_offset), truncation behavior, section fallback behavior, and the ticker-autoresolve feature. 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 dense but well-structured: purpose first, then usage examples and warnings, then parameter guidance, then sibling references. Every sentence adds distinct value—no filler or repetition. The paging explanation is clear and actionable.

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 (7 params, two invocation modes, paging, section filtering, output truncation), the description covers all essential aspects. The output schema is missing but the description explains return fields (truncated, next_offset) and text capacity. The sibling references close the gap for related tasks.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the description adds significant value beyond the schema: it explains the two invocation modes (accession vs. ticker+form_type), warns about the ticker mismatch risk and how to avoid it (use edgar_company_filings to resolve name to CIK), clarifies section fallback behavior, and describes paging semantics. This substantially enriches parameter 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 it retrieves 'AUTHORITATIVE full text of a SEC filing's primary document...HTML stripped to clean plaintext', specifying the sources (10-K/10-Q/8-K body) and use cases (going-concern language, ATM facilities, etc.). It also distinguishes from siblings by explicitly naming edgar_filing_documents and edgar_company_concept.

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

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

The description provides explicit when-to-use guidance ('Use for...does $TICKER disclose substantial doubt / going concern'), when-not-to-use via sibling references ('For the list of documents/exhibits...use edgar_filing_documents; for structured financial numbers use edgar_company_concept'), and clear alternatives. It also warns about the silent mismatch risk with tickers.

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=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, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral detail: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), lists returned fields, mentions patents API soft-fail until May 2025, and notes it is a single parallel call. 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 slightly long but well-structured with front-loaded examples. Every sentence adds value, covering usage, behavior, and return fields. It is not overly verbose for the complexity involved.

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 thoroughly explains return values: cik, company_name, recent_filings with URIs, fundamentals with specific fields, patents status, news fallback, and LEI. It also mentions source endpoints and limitations, making it complete for an agent to understand what to expect.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema: it explains that 'type' is only 'company', and 'value' should be ticker or zero-padded CIK (not names), with examples. This helps agents use parameters correctly.

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 explicit user intents ('Tell me about X', 'research Acme') and clearly states the tool returns a full cross-source profile of a US public company. It distinguishes itself from sibling tools by advising preference over chaining single-pack lookups, making purpose and differentiation very 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 explicitly states when to use this tool (holistic view, prefer over chaining) and when not to (names not supported, use resolve_entity first). It provides an alternative tool (resolve_entity) and gives clear input examples, offering excellent usage guidance.

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

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

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?

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and when spreads are meaningless. 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 dense and front-loaded with the main purpose. Every sentence adds value, though it is verbose. Could be slightly shortened but justified by 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?

Without an output schema, the description fully explains return values (leg-by-leg prices, matched spreads) and safety fields. It covers all necessary context for a complex tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: explains the distinction between topic and explicit params, lists all 10 topic shortcuts, provides concrete example values for explicit params.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, using specific verbs and resources. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue analysis.

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 two modes (topic shortcuts and explicit tickers), warns about false positives with compatibility_warning, and notes that most pre-mapped topics are not tradeable. However, it lacks explicit comparison to alternatives like polymarket_arbitrage.

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?

The description provides rich behavioral context beyond the annotations: it explains cascading internal lookups, graceful degradation when external sources are unavailable, and the output structure including labelled identifiers and an 'unresolved' list. It aligns perfectly with the annotations (readOnlyHint, idempotentHint, openWorldHint) and adds significant value.

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

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

The description front-loads with example queries, which is helpful, but then becomes quite lengthy with technical details about LEI, FIGI, and ISIN mapping. While every sentence adds value, the overall length trades off conciseness against completeness. A more structured breakdown (e.g., separate sections) would improve scannability.

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

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

Despite having no output schema, the description thoroughly covers return value structure (identifiers, sources, unresolved array), error handling (graceful degradation), and edge cases (ISIN inputs, non-US issuers). It is fully sufficient for an agent to understand the tool's input, behavior, and output without 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% with good descriptions. The description adds extra meaning beyond the schema: examples of valid values, explanation of ISIN-to-LEI mapping, and the distinction between company and drug entity types. This enrichment justifies a score above baseline 3, though the schema already does a solid job.

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 is extremely clear: it opens with concrete example queries, then explicitly states the tool's purpose as resolving user-spoken names to canonical/official identifiers. It distinguishes itself from sibling tools like edgar_ticker_to_cik and entity_profile by being the first-stop resolver for names, covering multiple identifier types across companies and drugs.

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 strong usage guidance: 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2–3 manual lookups. It does not explicitly state when NOT to use it (e.g., if you already have a CIK), but the examples and context make appropriate use clear. A small gap in exclusion cases keeps this from a 5.

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

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

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.