Edgar

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

Adds important behavioral context beyond annotations: default model (Workers AI, free), optional Anthropic with BYO key, cost implications. Annotations already cover safety (readOnlyHint).

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?

Concise and well-structured: first sentence defines the core action, then details parameters and use cases. No redundant sentences; 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?

Covers return format (per-model objects with score, confidence, signals, raw_response, combined view) and use cases. Lacks detail on combined view structure or 'signals' definition, but adequate for agent decision-making.

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?

Description adds significant value beyond input schema definitions: explains model options, entity examples, API key usage, and context purpose. All four parameters are enriched with usage guidance and examples.

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 probes LLMs to score visibility (0-100) per model, with specific verb and resource. It distinguishes from sibling tools by focusing on AI visibility scoring for marketing audits.

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 clear contexts for use: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly exclude alternatives or name them, but the usage scenarios are well-defined.

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 behavior. The description adds context: it routes to 3,775 tools, fills arguments, and returns structured answers with citation URIs. This supplements the annotations without contradiction, though it could mention any limitations or error handling.

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 and front-loaded with the key usage instruction. It is somewhat lengthy but every sentence adds value, covering purpose, scope, and behavior. Could be slightly more concise, but overall efficient.

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

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

Given the tool's complexity (accessing 3,775 tools) and the absence of an output schema, the description does an excellent job of conveying what the tool does, when to use it, and what to expect in response. It covers purpose, usage, and behavioral traits 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 coverage is 100% with detailed descriptions of the 'question' parameter and its aliases. The description does not add extra meaning beyond what the schema provides, so a 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's purpose: it's a question-answering tool that routes questions to a vast set of authoritative sources, returning structured answers with citations. It explicitly contrasts with web search and lists numerous domains, making its purpose unambiguous.

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

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

The description provides explicit guidance: 'PREFER OVER WEB SEARCH' and lists specific conditions (e.g., SEC filings, FDA data, real-world entities). It also gives trigger phrases and examples, effectively telling the agent when to use this tool instead of 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?

The description discloses key behaviors beyond annotations: costs one extra LLM call, returns explicit refusal reasons (listed in detail), and emphasizes that answers are extracted solely from tool results. No contradictions with annotations (all 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?

The description is front-loaded with the core purpose and usage, then provides detailed behavioral notes. Every sentence adds value; no superfluous text. Well-structured for quick agent comprehension.

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 specifies the return format including all fields and refusal reasons. It also covers cost implications and routing behavior. Complete for a tool with this complexity.

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

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

Schema coverage is 100% and the schema descriptions already explain the parameter (question) and its aliases. The description adds no new semantic meaning to the parameter; it only repeats what the schema provides.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads. It specifies the verb 'EXTRACTS the answer using ONLY what the tool result contains' and distinguishes it from the sibling ask_pipeworx by emphasizing grounded extraction.

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 guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and 'prefer ask_pipeworx for casual lookups.' This clearly states when to use and when not, with a direct alternative.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description extensively covers fan-out logic, response shapes, resolver contract, parent event extraction, news fallback handling, safety shortcuts, market closure scenarios, wide-spread flags, and resolution-rule risk. No contradictions with annotations.

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

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

The description is long but information-dense, front-loading purpose and usage. It could trim examples or consolidate classifier lists, but every section serves a purpose 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?

With 3 parameters and no output schema, the description covers all necessary aspects: input flexibility, processing workflow, output fields, error conditions, and edge cases (blocking behavior, illiquid markets, cancellation rules). 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 coverage is 100%, and the description adds significant context: market input format variants, depth options (quick vs thorough), and include_raw rationale. This meaningfully enhances understanding beyond the parameter descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, accepts multiple input formats (slug, URL, question text), and distinguishes itself from sibling tools with specific usage examples. It uses a specific verb ('Research') and resource ('Polymarket bet').

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 provides use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and lists classifier types. It does not explicitly state when not to use the tool or mention alternatives, but the detailed behavioral guidance compensates.

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), the description details that for companies it pulls latest 10-K financials, handles off-calendar fiscal years, and for drugs pulls adverse-event counts, approval counts, and trial counts. It also notes results are sorted and returns citation URIs.

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 but well-structured, starting with typical user queries and progressively adding detail. Every sentence adds value, though it could be slightly more concise without losing 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, the description explains return format (paired data + citation URIs) and covers both entity types with specific data fields. It is fully informative for a comparison 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?

The schema already covers both parameters with enums and descriptions, but the description adds context: what values mean for each type (tickers/CIKs vs drug names) and confirms the max items. This adds meaningful guidance 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 side-by-side comparison of 2–5 companies or drugs, with specific examples like 'Compare X and Y' and distinguishes from sequential lookups. It specifies data sources: SEC EDGAR for companies and FAERS for 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also explains sorting by primary metric, aiding correct usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral details: never invents (gaps[]), returns verbatim evidence with confidence, source, fetched_at, citation. Also notes paid plan for thorough depth. 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?

Concise single paragraph, front-loads key value. Every sentence adds information—no fluff. Well-structured with logical flow.

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, description explains return format (findings packet with evidence, confidence, source, etc.). Covers prerequisites, capabilities, and gives realistic latency estimate (15-60s). Fully adequate for a complex research 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 100%, but description adds meaning: explains depth values (quick=3, standard=5, thorough=8) and that thorough requires paid plan. Clarifies question is for broad/multi-part queries.

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 the tool's purpose: 'Grounded multi-source research in ONE call.' Describes decomposition, parallel routing, and structured findings. Explicitly distinguishes from sibling tool ask_pipeworx.

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: 'Use for broad or multi-part questions' and names alternative (ask_pipeworx for single lookups). Mentions prerequisites (Pipeworx account, paid plan for thorough depth).

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, idempotentHint=true, and destructiveHint=false, so the agent knows the tool is safe and idempotent. The description adds value by detailing that it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that results are ready to call directly, which is consistent with the annotations.

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

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

The description is front-loaded with the core purpose and provides a structured list of domains, followed by the return format and usage advice. It is somewhat verbose but each sentence contributes useful information, making it appropriately sized.

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 role as a discovery mechanism for a large set of sibling tools, the description covers the purpose, when to use, what it returns (with detail), and how to use parameters. It provides sufficient context for the agent to use it effectively without needing 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%—all parameters have descriptions. The description adds some context about the query parameter and aliases, but this largely mirrors the schema. The examples in the schema are already helpful, so the description provides marginal additional value.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains and emphasizes that it is a discovery tool, differentiating it from the numerous sibling tools that are specific to single 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?

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It provides clear usage context, though it does not list specific alternative tools by name.

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, idempotent, non-destructive. Description adds that it returns annual values with fiscal years, period ends, filing types, and resolves XBRL tags per filer. 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: tool purpose, source, usage pattern, examples, use cases. Every sentence adds value with no fluff. Front-loaded with 'AUTHORITATIVE' for emphasis.

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 full schema coverage, annotations, and output schema (implied), the description is complete: it explains what the tool returns, how to use, and what kind of data 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% with clear descriptions for cik and concept. Description adds examples, common metrics, and explains how tickers are auto-resolved and XBRL tag mapping, adding 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?

Clearly states it provides authoritative historical financials from SEC XBRL filings for US public companies, distinguishes from third-party scrapes, and gives examples. Differentiates from sibling tools like edgar_company_facts by focusing on XBRL tags.

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 gives use cases like 'what was AAPL's revenue in 2024' and contrasts with estimates, but does not explicitly exclude alternatives or specify when not to use. Sibling context exists but not directly addressed.

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, destructiveHint=false. Description adds context about the large payload, typical agent usage pattern, and emphasizes 'authoritative official numbers', which goes beyond annotations but is not critical for behavior.

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 two sentences plus an appended note. It is efficient and front-loaded, but the third sentence could be integrated. Still well-structured and without filler.

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

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

Given the output schema exists (not shown but stated), description explains the payload broadly. It covers the tool's role among siblings and typical usage, leaving little ambiguity.

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 schema coverage 100%. Description adds value by explaining how to obtain the CIK if needed ('Use edgar_ticker_to_cik to look up'), which is not in the input 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?

Description clearly states 'authoritative full XBRL fundamentals dump for a US public company by CIK' and specifies it returns hundreds of metrics with annual/historical values from SEC filings. It also distinguishes from sibling tool 'edgar_company_concept' by noting the scope difference.

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 (complete fundamental picture) and when not to (one metric -> use edgar_company_concept). Also mentions typical usage pattern (agents use once then narrow) and large payload considerations.

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 that it returns filing dates, form types, accession numbers, and document links. This is useful behavioral context beyond the annotations.

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

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

Concise yet comprehensive: three sentences cover purpose, input options, filtering, return content, use cases, and alternatives. Front-loaded with key information. 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 3 parameters with 100% schema coverage, annotations indicating safe read-only behavior, and presence of an output schema, the description fully covers usage, input formats, filtering, and return content. It also directs to sibling tools 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 coverage is 100%, but the description adds significant meaning: explains ticker_or_cik can be either ticker or CIK, provides examples for form_type (10-K, 10-Q, etc.), mentions default and range for limit (1-40, default 20). This goes 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 clearly states it provides an 'AUTHORITATIVE list of recent SEC filings' for a specific US public company using ticker or CIK. It details what it returns (dates, form types, accession numbers, document links) and distinguishes from sibling tools like edgar_company_concept and edgar_company_facts.

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

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

Explicitly states when to use: 'what did $TICKER recently file' or 'show me the last N proxy statements'. Provides when-not-to-use: for severity-classified 8-Ks prefer sec_8k_recent, for financial metrics use edgar_company_concept, for full XBRL use edgar_company_facts. Also specifies that form_type filter is optional.

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

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

Annotations already declare readOnly, idempotent, openWorld. The description adds critical behavioral context: data delay (~30-60 days), coverage scope (US-registered funds), and exceptions (unit investment trusts). 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?

Concise (~6 sentences) yet comprehensive. Front-loaded with purpose and immediately provides usage context. Every sentence adds value—no filler or repetition of schema.

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

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

Despite no output schema, the description fully explains return format (monthly portfolio: net assets, holdings count, top positions with name, CUSIP, value, %). Also covers limitations and coverage, making it complete for agent decision-making.

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% (both params described). The description reinforces the ticker parameter must be a fund ticker (not stock), adding value beyond schema. The limit parameter is not mentioned in description but schema already defines it clearly, so baseline 3 is exceeded.

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 portfolio holdings of US ETFs/mutual funds (specific verb+resource) and distinguishes from the sibling edgar_institutional_holdings. Examples like 'what does ARKK hold' solidify clarity.

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 guides when to use (fund N-PORT data) and when not (for manager-level holdings, use edgar_institutional_holdings). Notes limitations like legacy ETFs not filing N-PORT, and gives alternative tickers (IVV/VOO for S&P 500).

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds value by explaining transaction codes (P, S, A, M, G, F) and their significance (e.g., open-market purchases are strongest conviction signal). 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 informative but slightly lengthy. However, all sentences add value, and key information is front-loaded. Could be slightly more concise but acceptable.

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

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

No output schema, but description explains return data structure (parsed transactions with fields). Provides enough context for the tool's complexity, though could mention array nature.

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 parameter descriptions. Description adds value beyond schema by explaining the importance of include_derivatives default and mapping transaction codes to behavior, but schema already covers basic semantics.

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

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

The description clearly states it returns insider trading activity from SEC Forms 3/4/5, listing specific data fields (who, shares, price, holdings). It distinguishes itself from sibling tools like edgar_company_filings.

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

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

Explicitly says when to use (e.g., 'insider buying at $TICKER', 'did executives sell recently') and provides an alternative for raw filings (edgar_company_filings with form_type:'4').

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, idempotent, and non-destructive. The description adds behavioral context: it returns the latest quarterly 13F with aggregated holdings, explains 13F coverage (long equity only, excludes shorts), and notes value unit differences. 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?

The description is front-loaded with purpose and key details. Every sentence adds value, but it is slightly verbose (e.g., the note about value units could be more concise). Still well-structured.

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

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

Given no output schema, the description explains return format (top holdings, value, shares, %) and notes the report period and value unit differences. It covers sources, frequency, and limitations. Complete for a simple 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?

Both parameters have full schema descriptions (100% coverage). The description adds crucial context: ticker_or_cik is for the manager (not held stock), and explains the limit parameter. This goes beyond schema basics.

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 the stock portfolio of institutional investors from SEC Form 13F-HR, with specific examples like 'what does Berkshire own'. It distinguishes from sibling tools like edgar_company_facts by focusing on institutional holdings rather than company facts.

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

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

The description provides explicit guidance on when to use (e.g., 'what does Berkshire own') and notes limitations of 13F data. However, it does not explicitly state when not to use it or mention alternative tools for other Edgar needs.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds context about being authoritative and returning metadata + links, but does not disclose any unexpected behaviors beyond what annotations imply.

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

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

The description is extremely concise, with no redundant sentences. It is front-loaded with the most important usage advice ('PREFER OVER WEB SEARCH') and efficiently conveys purpose, scope, and return format.

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 parameters (1 required), an output schema, and clear annotations, the description covers all necessary context: what the tool does, when to use, what it returns, and how it contrasts with a sibling. No notable 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 description coverage is 100% — all parameters have descriptions in the input schema. The description adds minimal additional meaning beyond summarizing filter options (form type, date range) already documented in 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 it performs full-text search across SEC filings, with specific verb+resource (search filings) and filtering options. It also explicitly distinguishes itself from sibling tool edgar_company_filings, which is for specific companies.

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 ('what did $COMPANY say about X in their SEC filings') and when not to use ('not for a specific company; use edgar_company_filings'). It also recommends preferring this over web search for authoritative results.

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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds non-obvious behavioral traits: it's cheap, has no rate limit concerns, and returns specific fields {cik, cik_padded, company_name}. 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 concise at three sentences, with no wasted words. The most critical information (resolve ticker to CIK) is front-loaded. Every sentence adds value: purpose, usage guidance, behavioral characteristics.

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 nested objects), the presence of an output schema, and rich annotations, the description provides complete context. It explains the tool's role in the SEC tool family, return shape, and internal usage by other 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% for the single parameter 'ticker', with a clear description and examples. The description adds context beyond the schema: it specifies 'US stock ticker', provides an example, and explains the purpose (required by other SEC tools). This adds meaning beyond the schema's baseline description.

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

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

The description clearly states that the tool resolves a US stock ticker to the SEC's 10-digit CIK identifier, which is required by all other SEC tools. It specifies the verb (resolve) and the resource (ticker to CIK), and distinguishes itself from sibling SEC tools that require CIK as input.

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 'Call THIS FIRST' when you have a ticker and need to use other SEC tools. It lists specific sibling tools that require CIK. It also notes that most other tools accept tickers directly and call this internally, providing clear guidance on when to use explicitly (when you want CIK as data) and when not to.

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. The description adds beyond annotations: details the parallel fan-out across multiple sources, mentions USPTO PatentsView API sunset and soft-fail behavior, and lists specific return fields. 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?

The description is packed with information and front-loaded with example queries. While long, every sentence adds value. Slightly verbose in enumerating every return field, but still 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?

Despite no output schema, the description thoroughly explains what the tool returns (cik, company_name, filings with URIs, fundamentals sorted by period, patents, news, LEI) and notes limitations (patents soft-fail). Sufficient for an agent to understand the tool's capability.

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 critical meaning: explains the 'type' enum is limited to 'company', and 'value' accepts ticker or zero-padded CIK but not names, with a pointer to resolve_entity. This prevents misuse.

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 a full cross-source profile of a US public company, listing sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and returned fields. It distinguishes from siblings like edgar_company_filings and resolve_entity, which are single-purpose 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?

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises using resolve_entity first if only a name is available, avoiding failures.

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 destructive and idempotent behavior. The description adds context (stale data, sensitive data) but does not disclose further behavioral traits (e.g., return behavior on missing key).

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 action, each sentence adds value without redundancy. Extremely concise and well-structured.

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

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

Given the tool's simplicity (one required param, no output schema), the description sufficiently covers intent, usage scenarios, and complementary tools. 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 coverage is 100% and the description adds minimal detail beyond the schema's 'Memory key to delete.' Baseline 3 is appropriate given high schema coverage.

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

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

The description uses a specific verb ('Delete') and resource ('memory by key'), clearly stating the tool's action. It also mentions pairing with 'remember and recall,' distinguishing it 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?

The description specifies three concrete use cases: stale context, task completion, and clearing sensitive data. It also references complementary tools, but lacks explicit '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?

Description adds context beyond annotations by explaining the fetch-extract-emit process and output format. Consistent with readOnlyHint and destructiveHint=false.

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 efficient sentences plus a bullet list of use cases. Front-loaded with main action, 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 simple input schema (2 params) and rich annotations, description fully explains input, process, output, and use cases. No missing details.

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

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

Schema covers both parameters fully (100% coverage). Description does not add new meaning beyond stating extraction of key links and output format. 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?

Clear verb 'generate' and specific resource 'llms.txt file' with explicit format and purpose. Distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation.

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 indexing, own project, competitor audit) but does not mention when to avoid using it or alternatives 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?

Annotations already indicate readOnly, idempotent, etc. Description adds value by stating scope ('the caller's'), mentioning return fields, and implying behavior with the `include_inactive` parameter. 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 concise sentences cover purpose, output fields, and usage guidance with no superfluous text. Front-loaded with the essential action and resource.

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 and the presence of annotations, the description adequately covers purpose, usage, and output. However, it omits potential details like pagination or limits on returned subscriptions, leaving minor gaps for a complete context.

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

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

The only parameter `include_inactive` is fully described in the schema (100% coverage). Description does not add further semantics beyond mentioning 'active subscriptions', so baseline of 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, includes returned fields (id, type, etc.), and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. While not stating when not to use, it offers clear context for when this tool is appropriate.

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

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

The description discloses behavioral traits beyond annotations: rate-limited to 5 per day, free usage, no impact on tool-call quota, and how feedback is processed (digests read daily, direct roadmap impact). Annotations do not indicate these constraints, so the description adds essential context.

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

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

The description is concise at about 5 sentences, front-loaded with purpose and guidelines. Every sentence serves a purpose: stating the tool's function, enumerating use cases, setting expectations (rate limits, quota), and advising on proper usage. 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?

Given the tool's simplicity (sending feedback), the description is complete. It covers purpose, usage, behavioral traits, and parameter hints. No output schema is needed; the tool's return value is straightforward acknowledgment. The description leaves no ambiguity 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 description coverage is 100%, so the baseline is 3. The description does not add new parameter details beyond the schema, but it reinforces parameter usage by mentioning the 'type' field and providing examples. No significant added value 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's purpose: sending feedback to the Pipeworx team. It specifies types (bug, feature, data_gap, praise) and gives concrete examples of when to use each. It distinguishes itself from sibling tools, which are all research or entity-related, as a feedback mechanism.

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

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

The description explicitly states when to use the tool: for bugs, missing features, data gaps, or praise. It also provides a clear 'when not to' by advising not to paste the end-user's prompt. It mentions rate limits (5 per day per identifier) and that it's free and doesn't count against quota, offering comprehensive 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). This goes beyond the annotations.

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

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

The description is concise—three sentences plus bullet points—without any filler. It front-loads the purpose and organizes use cases clearly. 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's low complexity (one optional parameter, no output schema), the description covers all essential aspects: purpose, use cases, data source, privacy, and caching. It is fully self-contained.

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

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

Schema coverage is 100% and the schema description is adequate. The tool description adds context about window semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which enhances understanding beyond the enum values.

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 ('returns', 'calling on') and clearly states the tool's output: top tools, top packs, and total call volume. It distinguishes itself from sibling tools by focusing on trending data rather than individual queries or entity lookups.

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

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

Three explicit use cases are listed (discovering hot data, confirming canonical tool, aligning use case), providing clear context for when to use. However, it does not explicitly state when not to use or mention alternative 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?

Description goes far beyond annotations (readOnly, idempotent, non-destructive) by detailing internal logic: monotonicity, partition checks, semantic anchor, partition filter, fill check. It explains what happens in each mode and the response structure, providing rich behavioral context.

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

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

Description is comprehensive but verbose, with several paragraphs of dense technical detail. It front-loads the requirement but could be more concise or structured into sections to improve readability.

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

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

Given the tool's complexity, the description covers key aspects: usage modes, internal algorithms, response structure, failure modes, and cross-references to sibling tools. No output schema, but the description details the response fields. Mostly 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?

Both parameters are described in schema (100% coverage). Description adds extra context: clarifies the difference between modes, provides example valid inputs, and mentions that full URLs are accepted for event. Adds meaningful value 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?

Description clearly states the tool's purpose: find arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, and it is clearly differentiated from sibling tools like polymarket_edges and 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?

Description explicitly requires one of 'event' or 'topic' and advises on when to use each: event for a specific market, topic for cross-event scanning. It provides examples but does not explicitly state when not to use the tool or compare with alternatives in detail.

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 substantial behavioral context beyond annotations (readOnlyHint, idempotentHint, destructiveHint): caching (1h KV level), response structure including diagnostics, slippage netting, 24h-move warning, and filter skip reasons. 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?

Front-loaded with core purpose, but includes extensive model family details and parameter descriptions that could be condensed. Clear segment structure compensates, but overall longer than ideal.

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, but description explains response segments (by_segment, fed_candidates, _diagnostics) and edge cases like Fed bets. With 9 params and 100% schema coverage, it feels complete for the intended 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%, baseline 3. Description adds value: explains slippage_pp assumptions, why min_kelly doesn't filter partitions (min_partition_leg_kelly does), and tradeable-edge filters. Provides real-world context 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 states a specific verb ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and explicitly targets a use case ('what should I bet on today'). It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement.

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?

Clear primary use case is given. Knobs like min_liquidity and max_spread_pp are explained with guidance like 'Set to 5000 to drop thin-book opportunities'. Lacks explicit exclusions for sibling tools, but context is sufficient.

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

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

Annotations already declare read-only, open-world, and idempotent. Beyond that, the description adds rich behavioral details: response structure (tracked, expired, snapshot_dates), data source (daily polymarket_edges snapshots), computation details (decay from daily closes), and limitations (60-day TTL, no intraday data). 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-structured: core question first, then response fields, then limitations. Every sentence adds value. It could be tightened slightly but is concise enough for the complexity.

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

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

With no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and provides necessary context for interpreting results (e.g., median lifespan as competition clock). It also covers limitations, making it complete for an agent to use effectively.

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 both parameters well-described. The description adds modest extra meaning: clarifies 'days' as lookback and 'window' as snapshot family, and restates defaults. It adds a maximum of 30 for days, already implied by schema clamp. 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 provides 'edge persistence and decay telemetry' built from daily snapshots, answering exactly 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on temporal analysis of 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 explains the tool's context (e.g., a fresh wide edge vs. a 3-week-old edge) and provides limits (60-day TTL, decay from daily closes). It implies when to use it (to understand edge longevity) but does not explicitly mention when not to use or compare to alternatives beyond the implicit distinction.

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 indicate read-only, idempotent, non-destructive behavior, which the description confirms. It adds rich behavioral details: walks the order book ladder, returns specific fill metrics, and warns about thin books and directional risk. 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 relatively long but well-structured with clear sections for modes and returns. Every sentence adds necessary context given the tool's complexity. Could be slightly more concise, but content justifies 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?

No output schema exists, so the description fully explains return fields for both modes. Parameter descriptions are complete. It also addresses usage context relative to siblings and warns about failure modes, making it self-contained and comprehensive.

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. The description adds extra semantics: explains default side for basket (auto), clarifies size_usd meaning in both modes (max spend vs settlement notional), and provides default values and clamping. This 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 identifies the tool as a realizable-vs-theoretical edge check using live order-book depth, distinguishing between single-market and basket modes. It specifies exact parameters and outputs, and differentiates from sibling tools like polymarket_arbitrage and 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?

Explicitly states when to use the tool: before acting on polymarket_arbitrage signals or trades above ~$500. It warns about risks like unfilled theoretical edges and partial basket fills leading to directional risk, providing clear guidance on 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extensive behavioral context: response structure, safety fields, temporal alignment, and skipped leg counters. 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?

Well-structured with clear sections, but somewhat verbose. Every sentence adds value, but could be tightened slightly. Front-loaded with core 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?

Despite no output schema, the description fully explains response fields, safety mechanisms, and edge cases. Covers all necessary context for correct 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%. Description adds value by listing all topic shortcuts, providing examples, explaining the override relationship between topic and explicit parameters, and clarifying the behavior of each.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic and explicit) and explains the response content, differentiating it from siblings like polymarket_arbitrage.

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 explains when to use each mode, warns that pre-mapped topics often return compatibility_warning, and details conditions for safety fields. Provides clear guidance on when spreads are meaningful vs not.

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 destructiveHint. The description adds valuable context: scoping to identifier, listing all keys when omitting argument, and behavior of retrieval.

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 focused sentences plus a third on scoping/pairing. No wasted words, front-loaded purpose, excellent structure.

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

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

For a simple tool with low parameter count and no output schema, the description covers purpose, usage, scoping, and sibling relationships completely.

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 single optional parameter 'key' is well-described in both schema and description. With 100% schema description coverage, the description adds minimal extra 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 verb 'retrieve' or 'list' and the resource 'value previously saved' or 'keys'. It distinguishes the tool from siblings 'remember' and 'forget' by name.

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 recommends use for retrieving previously stored context (e.g., user's target ticker) and implies not for fresh data. It pairs with 'remember' and 'forget' to guide 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?

The description states that setting mark_read:true 'flag[s] returned events read' and 'the next call only shows newer ones,' implying a state change. However, the annotation readOnlyHint is true, indicating the tool should be read-only. This contradiction between description and annotation severely undermines 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 concise at five sentences, each serving a purpose: purpose, return fields, filtering options, mark_read behavior, and alternative access. Information is front-loaded and no redundant 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 there is no output schema, the description partially describes return fields (source, citation_uri, payload) but omits other possible fields and pagination details. However, it covers key usage scenarios and the alternative method, so it is largely complete but could be enhanced.

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 behavioral context (e.g., effect of mark_read) and reinforces the use of 'type' and 'since' with examples. This goes beyond the schema's basic descriptions, providing additional insight.

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,' specifying a verb and resource. It distinguishes from siblings like 'list_subscriptions' by focusing on fired events rather than subscription definitions.

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 guidance on when to use (e.g., polling, filtering by type and since) and mentions an alternative method (GET registry.pipeworx.io/alerts.json). However, it does not explicitly state when not to use the tool or compare it to any direct alternative among the sibling 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 safety (readOnlyHint, idempotentHint). Description adds detailed behavioral context: fan-out architecture, fallback from GDELT to GNews, USPTO soft-failure due to API sunset, return format (grouped changes with 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?

Front-loaded with query examples, then explains sources, parameters, and sibling distinction. Every sentence adds value, though slightly verbose for a single tool description.

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 key aspects: multiple data sources, fallback behavior, parameter formats, return structure (changes[], total_changes, URIs), and references alternative tool 'entity_profile'. No output schema but return format is described 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 coverage is 100%, baseline 3. Description adds value by explaining 'since' accepts ISO or relative formats, giving examples, and recommending '30d' or '1m' for typical monitoring. This goes beyond schema documentation.

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 provides a change feed for companies, fanning out to multiple sources (SEC, GDELT/GNews, USPTO). It uses specific verbs like 'What's new' and explicitly distinguishes from the sibling tool 'entity_profile' for static profiles.

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 clear guidance on when to use this tool for recent changes vs 'entity_profile' for static profiles. It also notes USPTO soft-fail behavior. Could mention more siblings but the distinction 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 behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' Annotations already indicate idempotentHint=true, but description elaborates on scoping and retention.

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 a single paragraph of 4 sentences, front-loaded with purpose. Every sentence adds value: purpose, usage guidance, behavioral details, and pairing with other tools. No filler.

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

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

For a tool with 2 simple parameters and no output schema, the description covers purpose, usage, behavioral details, and parameter hints. It is fairly complete, though could mention idempotent nature (already in annotations) and potential overwrite 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% with descriptions for both key and value. Description adds examples of key patterns (e.g., 'subject_property', 'target_ticker') and clarifies value as 'any text', which adds meaning beyond the basic 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?

Description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the resource (key-value pair) and verb (save/store), and distinguishes from sibling tools like recall and forget.

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 you discover something worth carrying forward... so you don't have to look it up again.' Also mentions persistence differences between authenticated and anonymous sessions. Does not 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds that each call cascades through several endpoints internally, replacing 2-3 manual lookups, providing useful behavioral context 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?

Front-loaded with examples and clear statement. A bit verbose but well-structured, each sentence adds value. Minor trim possible but overall 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?

No output schema, so description fully covers return details for both entity types, including citation URIs. Comprehensive for the tool's complexity.

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

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

Schema covers both parameters with descriptions, but description adds significant detail for each type: 'company' returns ticker, CIK, company_name, citation URI; 'drug' returns RxCUI, ingredient, brand, citation. This adds 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?

Starts with clear usage examples ('ticker for...', 'CIK for...'), explicitly states purpose ('resolve a user-spoken NAME to the canonical/official identifier'), and distinguishes from sibling tools by noting it replaces multiple manual lookups.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context for when to use. Does not explicitly state when not to use, but it is implied (when ID already known).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details: probes each entity, ranks by score, returns score, confidence, signal density. 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?

The description is 3-4 sentences, well-structured, and front-loaded. 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?

Given the tool has 4 parameters, no output schema, the description covers purpose, usage, parameter roles, and output format (ranked list with score, confidence, signal density). It is fully adequate.

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

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

Schema coverage is 100%, but the description adds meaning: first entity is subject for narrative, entities array should be 2-8, explains models and _apiKey. This adds significant context 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 that the tool compares AI visibility across multiple entities, uses ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (different comparison).

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

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

The description provides a use case: 'Useful for competitive AI-marketing audits' and implies alternatives by mentioning ai_visibility_check. However, it does not explicitly state when not to use this tool versus 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?

Discloses that it fans out across two services, returns detailed summary fields, per-advisory details, links, and alternative versions. Notes that bundlephobia's first measurement can take 5-30s and how failures are reported (sources_failed). Does not contradict annotations (all safe, read-only hints).

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?

Single sentence with multiple clauses, but every element is necessary. Front-loaded with main purpose. Could be slightly more structured (e.g., bullet points), but within character limits 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?

Without output schema, description fully specifies return structure: summary block fields, per-advisory detail, links, recent alternative versions. Also covers ecosystem boundaries, default version behavior, and failure handling. 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 already describes both parameters fully (100% coverage). Description adds context: package is npm name, scoped packages accepted, version defaults to latest. Also explains the composite fan-out behavior, adding meaningful usage guidance 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?

Description clearly states it's a composite check for adding npm packages, covering deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency' with explicit scope (npm ecosystem). Differentiates from siblings because no other tool does this.

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 agent asks about safety, popularity, size, or cost of adding a package. Also notes limitations: NPM only in v1; other ecosystems should use deps.dev:version directly. Mentions partial failures and graceful degradation.

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. Description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and return of character offsets and similarity scores.

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

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

Three sentences with no fluff. First sentence states action, second provides use case and benefits, third adds technical details. 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?

Given no output schema, description explains return format (passages with offsets and scores) and technical constraints. Also mentions integration with ask_pipeworx_grounded, making it self-contained for an agent.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds value with natural-language query examples, default limit behavior, and context about max chars, enriching understanding 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?

Description clearly states semantic search inside a fetched record, with specific examples like SEC 10-K body. Distinguishes from sibling ask_pipeworx_grounded, and contrasts with other search tools.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits like saving context and returning passages with offsets. Mentions pairing with ask_pipeworx_grounded, providing a clear use pattern.

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 provide non-readOnly, openWorld, idempotentHint=true, non-destructive. The description adds value by detailing auth requirements, delivery channel behaviors (webhook signing, SMS cap), and type-specific parameters. However, the idempotentHint=true annotation contradicts the implication that each call creates a new subscription, which the description does not clarify.

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. It front-loads the core purpose, then breaks down types and delivery. Each sentence adds value. Slightly long but not wasteful.

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 types, delivery channels, requirements, return value, and limitations. No output schema exists, so the description compensates by mentioning the returned id. Missing details on idempotency or error cases, but overall adequate for a 3-parameter 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 all parameters. The description goes beyond by providing concrete examples for each type's params and detailed delivery channel options (e.g., webhook HMAC signing, SMS verification). Every parameter is richly explained.

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 'Creates', the resource 'proactive monitoring subscription to a live-data event stream', and the outcome 'Returns the new subscription id'. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on 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?

Provides explicit context for when to use, including requirement for Pipeworx OAuth account, supported types with examples, delivery channels, and limits. Does not directly exclude scenarios or compare with alternatives, but the context is sufficient.

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

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

Annotations already cover readOnly, openWorld, idempotent, destructive hints. Description adds behavioral context: returns categorization with example questions and tool shapes from a live catalog, which is beyond safety profile.

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 comprehensive but slightly long. It is well-structured with common queries first, then output explanation, then usage guidance. Could be tighter but still 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?

Given no output schema, description explains return format (category-bucketed examples with tool+argument shape). Covers purpose, usage, parameter, and output thoroughly for a simple 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 100% for the single optional parameter 'topic'. Description adds examples of focus areas and explains the effect of omitting topic, providing context beyond the schema description.

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

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

Description clearly states this is the onboarding entry point for knowing what to ask Pipeworx. It returns category-bucketed example questions with exact tool/argument shapes, distinguishing it from sibling tools like ask_pipeworx or 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use the topic parameter or omit it.

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

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

The description adds context beyond annotations: it clarifies that the row is deactivated (not deleted) and preserves historical events. This aligns with 'destructiveHint: false' and 'idempotentHint: true', and provides useful behavioral details.

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 two sentences, front-loaded with the action, and contains no extraneous information. 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?

For a simple tool with one parameter and no output schema, the description covers the action, ownership constraint, and side-effects (soft delete, historical availability). It's complete for agent decision-making.

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

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

Schema coverage is 100%, so the schema already documents the 'id' parameter. The description mentions cancellation 'by id' but adds no new parameter semantics beyond referencing the schema and linking to 'subscribe'.

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 cancels a subscription by ID, using a specific verb ('Cancel') and resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 ownership enforcement ('only cancel your own subscriptions'), which guides appropriate usage. It also explains the deactivation effect, though it doesn't explicitly list alternatives to avoid confusion with other 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 indicate safe read-only, open-world, idempotent behavior. The description further details the returned verdict types, extracted structured form, actual value with citation, and percent delta. It also notes the tool replaces 4-6 sequential calls, adding behavioral context 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 slightly long but each sentence is substantive: examples, usage guidance, scope, return details, and efficiency benefit. Front-loaded examples aid quick comprehension. Minor redundancy could be trimmed, but overall it 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?

For a single-parameter tool with no output schema, the description is remarkably complete. It covers purpose, usage context, scope limitations, return value structure, and even replacements for multiple calls. No gaps are apparent.

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

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

With 100% schema description coverage, baseline is 3. The description adds value by providing natural-language examples and clarifying the claim format and scope, enhancing the schema's already good documentation.

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: natural-language claim verification against authoritative sources. It provides multiple example queries and specifies the domain (company-financial claims via SEC EDGAR + XBRL), distinguishing it from sibling tools that handle Edgar data or other research 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?

Explicitly says 'Use whenever the agent needs to check factual correctness' and defines the scope (v1 supports company-financial claims). It implicitly excludes other claim types but does not provide explicit when-not or alternative tools; the context of sibling tools and scope statement suffice.

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