sec

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful non-obvious context: the default free Workers AI model, the BYO Anthropic key with direct cost to the user, and a detailed return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 three sentences: core action, default behavior/cost, return format, and use cases. It is front-loaded with the purpose and every sentence contributes new information without redundancy.

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

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

Despite lacking an output schema, the description explains the return shape and key parameters (model selection, API key, context). It covers the main behavioral nuances (free default, BYO key cost) and use cases. For a read-only tool, this is 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%, so the baseline is 3. The description adds value beyond the schema by indicating the default model (workers-ai), the cost implications of using Anthropic, and the role of 'context' for disambiguation. This extra context justifies a 4.

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 a specific verb and resource. It defines the scope (business/brand/product/topic) and mentions default vs. optional models, but does not explicitly distinguish it from sibling tools like scan_competitor_ai_presence.

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 names concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass _apiKey. However, it does not explicitly mention alternative tools or when not to use this tool, so it stops short of a full 5.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint) already convey safety, but the description adds concrete behavior: routing across 5,621 tools, filling arguments, returning structured answers with pipeworx:// citation URIs. This goes beyond the annotations and helps the agent understand the internal behavior and output format.

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 critical directive ('PREFER OVER WEB SEARCH') and then expands into domains, routing behavior, and usage scenarios. Though relatively long, every sentence adds value—examples, alternatives, and news handling are all useful—so it earns a 4 rather than a 5 due to some redundancy ('START HERE' repeated).

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 default entry tool with no output schema, the description comprehensively covers the function, scope, return format, and selection criteria. It even provides examples and edge-case handling (news, breaking news), leaving the agent with all necessary information to call it correctly.

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

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

Schema description coverage is 100%: each of the 6 parameters is documented with 'Alias for question' and the primary 'question' parameter has a clear description. The tool description itself does not explain parameters beyond what the schema provides, so it meets the baseline of 3.

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

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

The description clearly states that the tool routes questions to over 5,600 tools and returns structured answers with citations, distinguishing it from siblings by naming ask_pipeworx_grounded and deep_research as specific alternatives. It explicitly lists covered domains and phrasing examples, leaving no ambiguity about its purpose.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides guidance on when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It also addresses news usage, making the selection criteria unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and no destructive actions, so the safety profile is covered. The description adds important behavioral context: it is a beta with experimental routing, possibly identical to ask_pipeworx when no candidate is active, and falls back to nothing (full working router). This goes beyond the annotations without contradicting them.

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

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

The description is well-structured and front-loaded with the core purpose (beta version), then explains current state, usage, and fallback behavior. Each sentence adds value, and it is appropriately sized for the complexity of a router with experimental features.

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 is a universal router with a huge toolset, the description provides sufficient context: it confirms it is fully functional, explains the beta nature, and points to ask_pipeworx for detail on the exact behavior. It does not include an output schema, but it states the response shape matches ask_pipeworx, covering return expectations.

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 has 100% description coverage for all 6 parameters (aliases for 'question'), and the description adds that arguments are identical to ask_pipeworx, which reinforces the alias structure. However, the description does not provide additional semantics beyond what the schema already states, so it stays at the baseline for full 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 clearly states it is a beta version of ask_pipeworx, a universal router that handles the same 5,621 tools with identical arguments and response shape. It explicitly names the sibling (ask_pipeworx) and the difference (experimental routing), making it easy to distinguish from the stable variant.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This gives clear when-to-use guidance and implies ask_pipeworx as the alternative for stable routing, though it doesn't explicitly state 'when not to use'.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses the internal routing, the extraction-only-from-tool-result behavior, the exact success and refusal return shapes, and the extra LLM call cost. This substantially exceeds what annotations provide and helps an agent anticipate side effects and failure modes.

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

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

The description is dense but every sentence carries essential information, from the core differentiator to return formats, use cases, and cost trade-offs. It is front-loaded with the most important differentiator and structured so an agent can quickly extract invocation guidance without superfluous 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?

Despite having no output schema, the description fully specifies the success and failure return structures, refusal reasons, and when to prefer the sibling tool. For a high-complexity tool with rich annotations and no output schema, this description is complete enough for an agent to call it correctly and interpret results.

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

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

Schema coverage is 100% and the schema already documents 'question' along with aliases. The description adds no additional parameter-level detail, but it does imply the question must be answerable from tool results, which is a usage nuance rather than parameter semantics. Baseline 3 is appropriate when the schema fully covers parameters.

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 this as a hallucination-resistant answer mode that extracts answers strictly from tool results, with a specific verb ('ask') and resource ('Pipeworx'). It differentiates from sibling ask_pipeworx by emphasizing the grounded extraction and explicit refusal behavior, so an agent can distinguish it without opening the schema.

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

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

It explicitly states when to use ('whenever an answer will be quoted, cited, or acted on'), provides examples of high-stakes domains, and contrasts with ask_pipeworx for casual lookups due to the extra LLM call. This gives clear selection criteria and an explicit alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, and the description adds extensive behavioral context: response shapes, resolver contract with match confidence, parent-event extraction, news fallback behavior (GDELT 429 handling), safety short-circuits (low_confidence_match, market_closed_or_inactive), and resolution-rule risk (cancellation_rule). It discloses blocking paths, field suppression, and illiquidity warnings—far beyond annotation basics.

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

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

The description is long but well-structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). It front-loads the core purpose and usage in the first two sentences. While every sentence adds value, the length is substantial and could be slightly trimmed without losing critical details; a 4 acknowledges the excellent organization despite verbosity.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does thoroughly: result.market fields, result.analysis with model probability and edge, result.evidence, market_match_confidence, parent_event structure, news fallback fields, and cancellation_rule semantics. It also covers edge cases like low-confidence matches, closed markets, and wide spreads. The description is exceptionally complete for a tool of 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% with descriptions for all three parameters. The description adds extra meaning beyond the schema by providing examples for the 'market' parameter (slug, URL, question text) and describing how depth affects fan-out (quick vs thorough) with real-world examples (BTC bet → coingecko + fred + gdelt+gnews). It also explains the include_raw parameter's impact on response size, which is not fully covered by the schema's simple description.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly outlines the tool's workflow (resolve, classify, fan out, return evidence) and distinguishes it from siblings by focusing on Polymarket bet research and the 'should I bet on X' use case.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples for different market categories (BTC, Fed, Hormuz, etc.), giving clear usage context. It doesn't explicitly name sibling tools as alternatives, but the 'Use for' phrasing plus detailed examples effectively guides selection.

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 readOnly and idempotent hints. Description adds substantial behavioral context: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, returns paired data with pipeworx:// citation URIs, and replaces 8-15 sequential lookups. 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 longer than the minimum but every sentence adds value: trigger phrases, use guidance, type-specific details, sorting behavior, and output format. It is well-structured and front-loaded with usage intent, though slightly dense.

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 2-param tool with no output schema and strong annotations, the description covers input semantics, data sources, sorting, and return format (paired data + citation URIs). It also explains the efficiency advantage, making it sufficiently complete for correct invocation.

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

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

Schema covers 100% of parameters with descriptions and examples. Description adds meaning by explaining type-specific data pulls (company: 10-K financials; drug: FAERS/FDA/trial counts) and clarifying values as tickers/CIKs or drug names beyond schema. This adds 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 side-by-side comparison of 2-5 companies or drugs, with specific verb 'compare' and resource types. Distinguishes from sequential single-pack lookups and says ALWAYS PREFER, making its purpose and advantage explicit.

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 usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists trigger phrases ('X vs Y', 'which is bigger'). This clearly indicates when to use and implies when not to (for single entity lookups).

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

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

Annotations already signal read-only, idempotent, open-world behavior, but the description adds substantial context: account and paid-plan requirements, latency expectations, gap[] handling with a 'never invented' guarantee, citation_uri fetchability, hop fields, contradictions[], and semantic excerpting. 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 front-loaded with critical account and routing information, and every major section serves a purpose given the tool's complexity. However, it is quite long and partially duplicates depth parameter semantics already fully documented in the schema, so it could be tightened.

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

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

Despite having no output schema, the description specifies the findings packet contents, gap[] behavior, citation_uri fetchability, hop fields, contradictions[], excerpting strategy, and latency. An agent has enough context to select the tool, invoke it correctly, and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining account/paid-plan implications for depth levels, providing concrete example questions, and clarifying that multi-part questions are intended. Some depth details repeat the schema, so it is not a 5.

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

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

The description states a specific verb+resource: grounded multi-source research across Pipeworx's 1,472 structured data sources in one call, decomposing questions into facets and routing them to tools. It explicitly distinguishes itself from open-web search and from the ask_pipeworx sibling.

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

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

The description gives clear when-to-use and when-not-to-use guidance: prefer ask_pipeworx when not signed in, for single lookups, or for breaking/current-events topics; use deep_research for broad/multi-part structured-data questions. It names alternatives and the conditions that select them.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by explaining the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This adds context about what the agent receives and that no further lookups are required.

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 includes a long but informative list of domains. It contains four sentences, each serving a purpose (purpose, when to use, return behavior, priority guidance). The domain list is slightly verbose but valuable for an agent to understand the tool's coverage.

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

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

For a discovery tool with no output schema, the description does a strong job explaining what it returns (tool names, descriptions, full input schemas with examples) and that results are directly callable. It also covers intended usage contexts. Minor gaps include not specifying how results are ranked or whether search is limited to the current toolset, but these are inferable.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters, including aliases and the limit. The description only adds the 'top-N' concept, which is already reflected in the limit parameter's schema description. Thus it meets the baseline, but does not add significant 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 opens with 'Find tools by describing the data or task,' which is a specific verb+resource definition. It clearly distinguishes the tool from sibling tools as the discovery/meta tool, especially with the explicit 'Call this FIRST' guidance.

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 it: 'Use when you need to browse, search, look up, or discover what tools exist for...' and provides a comprehensive list of domains. It also instructs to call it first when many tools are available, effectively telling the agent when not to use 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?

Annotations already declare readOnlyHint/openWorldHint/idempotentHint and destructiveHint=false. The description adds substantial context beyond that: it fans out across multiple upstream sources, soft-fails on USPTO sunset, uses GDELT→GNews fallback, and specifies exact return fields. No contradiction with annotations.

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

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

The description is dense but well-structured, starting with example queries and then giving a logical breakdown of sources and returned fields. It is longer than strictly necessary, with some repeated guidance, but every section earns its place for a complex tool.

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

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

With no output schema and high complexity, the description fully enumerates return components (cik, recent_filings, fundamentals, patents, news, LEI), input constraints, fallback behavior, and failure modes. This makes the tool's behavior predictable and complete 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% and already includes ticker/CIK examples, zero-padding, and the name-not-supported caveat. The description largely duplicates this information, so it adds limited new semantic value; baseline 3 is appropriate.

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

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

The description opens with concrete user phrasings and clearly states it returns a 'full cross-source profile of a US public company in ONE parallel call,' giving a specific verb, resource, and scope. It also differentiates itself from sibling single-pack lookups by explicitly positioning itself as the holistic alternative.

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

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

It explicitly instructs to 'ALWAYS PREFER' this tool over chaining SEC/XBRL/news lookups when a holistic view is requested. It also delineates when not to use it, stating names are not supported and directing users to resolve_entity first, which is clear alternative guidance.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds context about the type of data (sensitive data saved earlier) and that the action is a deletion, which is consistent with the annotations. It does not go into further behavioral detail like irreversibility, but with annotations covering the main traits, this is adequate.

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

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

Two sentences deliver purpose and usage without filler. Every clause contributes meaningful information, and the text is appropriately front-loaded with the action.

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

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

For a one-parameter destructive tool, the description provides purpose, usage context, and sibling relationships. Annotations cover destructive and idempotent behavior, and the schema fully describes the parameter. No output schema exists, so return value documentation is not expected. The description is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema has 100% coverage of the only parameter, 'key', described as 'Memory key to delete.' The description reinforces that the key identifies the memory but doesn't add new semantics beyond the schema. This meets the baseline for high schema coverage.

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

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

The description opens with 'Delete a previously stored memory by key' — a specific verb and resource that clearly distinguishes it from siblings like remember (store) and recall (retrieve). The name 'forget' reinforces the delete semantics, making the tool's 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 second sentence provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember and recall,' which guides tool selection. No explicit 'when not to use' is given, but the positive guidance 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral detail beyond annotations: it fetches the page, extracts title/description/key links, and emits a single text blob in standard llms.txt markdown format. This explains the process and output without contradicting 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 three sentences, front-loaded with the core purpose, and each sentence earns its place: purpose, process, and use cases. No redundant wording or filler.

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

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

For a simple two-parameter tool with a clear output (a text blob) and strong annotations, the description covers what the tool does, how it does it, and when to use it. No output schema exists, but the description sufficiently explains the return value's nature and format.

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 'url' and 'max_links' have descriptions). The description does not specifically detail the parameters but implies the URL is fetched and links are extracted. Since the schema already covers parameter meaning, a baseline of 3 is appropriate.

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

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

The description uses a specific verb+resource construction ('Generate a production-ready llms.txt file for any URL') and clearly distinguishes itself from siblings by focusing on the act of generating the file itself, versus tools like 'scan_competitor_ai_presence' or 'ai_visibility_check' which likely just assess visibility.

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

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

The description provides three concrete use cases: getting a client's site indexed, drafting your own llms.txt, and auditing a competitor. This gives clear context for when to use the tool. It does not explicitly mention alternatives or exclusion criteria, but the use cases strongly imply the intended scenarios.

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 false, so the safety profile is known. The description adds context about return content (revenue, net income, total assets) and the auto-resolution of ticker/name to CIK, but does not disclose rate limits, pagination, or further processing 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?

Two tightly written sentences that front-load the verb and resource, then provide return value examples. No redundant filler; each clause adds information, making it appropriately 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?

For a single-parameter read-only tool with an output schema and annotations, the description is adequate. It explains what data is returned and the identification methods, though it could mention temporal scope or exactly how 'over time' is represented. Given the output schema, it is sufficiently 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?

The schema has 100% coverage for the single cik parameter, stating it accepts CIK, ticker, or name with auto-resolution. The description repeats this identification method but adds no new syntax or format details beyond the schema, so the baseline 3 applies.

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

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

Description clearly states the tool retrieves XBRL financial facts for a company, specifying the resource ('financial facts') and the identification methods (CIK, ticker, name). It distinguishes from sibling tools like get_company_filings by focusing on facts rather than 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?

The description implies usage when financial facts are needed, but does not explicitly compare to alternatives such as get_company_filings or search_companies. No exclusion criteria or when-not-to-use guidance is provided, leaving it to the agent to infer suitable contexts.

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=false, so the tool's non-destructive nature is known. The description adds useful behavioral context: it returns filing dates, form types, and accession numbers, and supports filtering by form type. It does not define 'recent' precisely, but with annotations covering safety, this is sufficient.

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, front-loaded with the core action and resource, followed by return fields and optional filtering. No redundant phrases or filler; every word 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?

With a full input schema, output schema, and informative annotations, the description covers all essential aspects: purpose, flexible input, optional filtering, and return data. For a low-complexity read-only tool, this is complete.

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

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

Schema coverage is 100%, and both parameters (cik and form_type) are well documented in the schema itself, including auto-resolution of ticker/name. The description largely reiterates this information rather than adding new semantic detail, so it meets the baseline but doesn't exceed it.

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

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

The description clearly states the tool's function: retrieving recent SEC filings for a company, with explicit mention of flexible identifiers (CIK, ticker, company name) and optional form-type filtering. This distinguishes it from siblings like get_company_facts and search_companies, making the purpose unambiguous.

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

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

The description conveys a clear use case: when you need recent SEC filings for a company with specific returned fields and optional filtering. It does not explicitly name alternatives or exclusions, though the sibling context (e.g., get_company_facts) implies a different purpose, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds worthwhile behavioral detail beyond that, including the scope (caller's subscriptions), the default active-only filter, and the specific fields returned. This enriches the agent's understanding of what to expect.

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

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

The description is three sentences: the first states the main function, the second lists return fields, and the third gives usage guidance. It is front-loaded, concise, and every sentence contributes value without redundancy.

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

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

For a simple list tool with one optional parameter, rich annotations, and no output schema, the description covers purpose, scope, return format, and use case. The schema fully handles parameter semantics, so nothing important is missing.

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

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

The input schema fully describes the single parameter (include_inactive) with a clear description and default value. The description only reinforces the active-only default by saying 'active subscriptions' but does not add meaning beyond the schema. Baseline 3 is appropriate under full 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 clearly states the tool's action ('List') and resource ('the caller's active subscriptions'), and also enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count). This differentiates it from sibling tools like subscribe and unsubscribe, which perform different actions.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies when to use the tool and indirectly points to alternatives (subscribe/unsubscribe), though it does not name them explicitly or state when not to use it.

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

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

Annotations only indicate non-readOnly/non-destructive, leaving room for the description to explain behavioral nuance. It does so thoroughly: explains the claim_token mechanism for later retrieval, rate limits (5/day), that it's free, doesn't count against quota, and that the team reads digests daily. This goes well beyond annotation hints and sets clear expectations for the side effects of filing feedback.

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?

Despite being long, the description is front-loaded with purpose, then logically progresses through usage boundaries, message guidance, claim token flow, and rate limits. Every sentence adds unique value; there is no fluff or redundancy. The structure makes it easy for an agent to parse and act on.

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

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

The tool has no output schema, but the description compensates by explaining return values (claim_token, status of prior reports) and the overall feedback workflow. It covers all necessary contextual elements: types, exclusions, message expectations, account handling, and operational constraints, making the tool fully 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?

Even though schema descriptions cover 100% of parameters, the description adds significant context: it maps the 'type' enum values to real-world scenarios ('bug', 'feature', 'data_gap') and explains the claim_token usage pattern (pass it back alone to retrieve status). This gives the agent deeper understanding of how to construct calls beyond what the schema provides.

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

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

The description uses a specific verb ('Tell'), identifies the resource ('Pipeworx team'), and clearly distinguishes this from sibling tools by framing it as feedback (broken, missing, needs to exist). It lists concrete feedback categories, making the tool's purpose unmistakable and differentiated from query/analysis tools.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data... a tool you wish existed...'), and provides an important exclusion: only for tools served by this Pipeworx connection, not other MCP servers. It also gives actionable guidance on how to describe issues (in terms of Pipeworx tools, not end-user prompts), which serves as effective usage direction.

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

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

Annotations already establish read-only/idempotent safety, but the description adds meaningful behavior beyond that: it's self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and is cached 5min-1h. This gives the agent crucial expectations about freshness and privacy.

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

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

The description is compact, front-loaded with the core value proposition, and uses a numbered list for use cases. Every sentence provides distinct information: purpose, outputs, use cases, data provenance, privacy, and caching. 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 simple read-only analytics tool with one optional parameter, the description covers purpose, use cases, output composition, privacy, cache behavior, and window semantics. The lack of an output schema is mitigated by explicitly listing what is returned. This is 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?

The schema covers 100% of the single parameter and its enum, but the description adds interpretive value: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent reason about which window to choose beyond the raw schema text.

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

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

The description opens with a specific verb+resource: 'What other AI agents are calling on Pipeworx right now' and explicitly lists the outputs (top tools, top packs, total call volume). This clearly distinguishes it from siblings like discover_tools, which is about broader tool discovery.

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 'Useful for' section enumerates three concrete scenarios (hot data sources, canonical tool confirmation, alignment with agent needs) and explains window choice across short vs. longer lookbacks. It lacks explicit 'when not to use' or alternative tool names, but the context is strong.

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

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

Annotations already declare readOnly, non-destructive, and idempotent. The description goes far beyond by explaining the fill check (realizable_edge_pp <= 0 means 'do not trade it'), the semantic anchor threshold (≥0.30 Jaccard), the partition filter, and the exact response structure. 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?

Though long, the description is dense and well-organized. It front-loads the core purpose, uses semicolons and parentheticals to group related details, and every sentence earns its place. The clear progression from modes to filters to response to fill check makes it easy to parse.

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

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

With no output schema, the description compensates by specifying the response fields (opportunities[], gap_pp, partition_check, suggested_trade, etc.). It covers all essential aspects of the tool: modes, edge cases, filters, safety checks, and cross-tool references. Nothing crucial is missing.

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

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

Schema covers 100% of parameters with solid descriptions, but the description adds crucial context beyond it: the no-args mode (trending_scan) isn't in the schema, event is recommended for specific markets, and topic is explained with the flattening/union comparator behavior. This enriches the parameter meaning significantly.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings like polymarket_edges and polymarket_fill_risk by naming its unique mechanisms and output.

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 three calling modes (no args, event, topic) with concrete examples and a recommendation ('event (recommended for a specific market)'). It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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, but the description adds substantial behavioral context: detailed model family mechanics (e.g., 'lognormal barrier from 90d FRED log-returns', 'GDELT 7d/21d article-volume ratio'), edge computation net of slippage, Kelly caps, the 24h-move warning, partition filter rules, and response diagnostics. It also discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'). 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 well-structured: one-sentence summary, then segment explanations, response fields, knobs, diagnostics, and caching. It contains specific constants (e.g., 'tennis 1.02, soccer 1.10, MMA 1.15') and conditionals ('partitions with >20% placeholder fraction skipped entirely') that earn their place. It is dense but not redundant; could be trimmed for quicker scanning, but complexity justifies the 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?

Despite no output schema, the description thoroughly describes the response shape: 'by_segment{model_driven,structural_arbitrage,concentrated_longshot}', diagnostics with funnel counters, and top-level fields like fed_candidates/fed_note. It also explains why a segment might be empty ('top-N stale, all candidates failed gates, knob dropped them') and the caching key. This is unusually complete for a tool of 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% (all 9 parameters have descriptions), so baseline is 3. The tool description adds meaning beyond the schema by explaining the strategic purpose of the 'TRADEABLE-EDGE KNOBS' and clarifying subtle behaviors like min_partition_leg_kelly applying to per-leg Kelly inside top_legs. It does not restate each parameter's type/format but provides higher-level filter logic, which is valuable.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_fill_risk by focusing on model-driven edge discovery across top markets.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains when knobs like min_liquidity/max_spread_pp should be used ('set to 2 to require tight books') and why Fed bets are excluded. However, it does not explicitly name alternative tools or say 'use X instead,' so it lacks the when-not guidance of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description adds rich behavioral context: how snapshots are written (cache-miss), why snapshot gaps occur, the 60-day TTL limit, and that decay is computed from daily closes rather than intraday. It also explains the meaning of expired opportunities and the 'competition clock' concept.

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

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

The description is long but densely informative, with clear structural labels (Args, RESPONSE, LIMITS) and front-loaded purpose. Every sentence adds value, explaining response fields and operational limits without redundancy.

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

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

With no output schema, the description thoroughly explains all return fields (tracked[], expired[], snapshot_dates[]) including sub-fields like first_seen, trend, decay_pp_per_day, and lifespan_days. It also covers limitations (TTL, data gaps, daily vs intraday), making it complete 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?

The input schema already provides full descriptions for both parameters (days, window) with defaults and ranges. The description repeats defaults ('default 14, max 30', 'default 1wk') but adds minimal new semantics like 'snapshot family' and cache-miss behavior. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states it provides 'Edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling polymarket_edges by focusing on the temporal dimension of edges rather than current snapshots.

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 implies when to use the tool by explaining the use case ('a fresh wide edge and a 3-week-old wide edge are different trades') and describing what the response contains (tracked, expired, snapshot_dates). It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it over polymarket_edges.

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=true and destructiveHint=false, but the description adds substantial behavioral context: it walks the order-book ladder, compares top-of-book vs VWAP, reports per-leg fill details, and flags 'forced_directional_risk' legs. It also discloses the failure mode of partial fills converting an arb into directional position—information beyond the annotations that is critical for safe use. No contradiction with annotations.

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

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

The description is long but well-structured with SINGLE-MARKET and BASKET sections, and it is front-loaded with the core purpose. Every sentence carries operational detail—no filler—but the density may make it slightly heavy for quick scanning. It earns its length 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 no output schema and a complex two-mode tool, the description enumerates all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and basket-specific outputs). It also names edge cases like thin_legs and forced_directional_risk, and explains how to interpret the results in the broader arbitrage workflow. This is fully complete for an agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, but the description adds important interpretive value: it explains the mutual exclusivity of market vs event ('REQUIRES one of...'), clarifies size_usd semantics per mode ('max spend on buys, target proceeds on sells' vs 'settlement notional'), and defines the auto default for basket side. This goes beyond the bare schema field descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which precisely identifies the tool's function. It also distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by framing itself as the pre-trade verification step for those signals.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides the rationale—theoretical overround on thin books is not capturable and partial basket fills create unhedged directional risk—which clarifies when it is necessary and why alternatives are insufficient on their own.

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 false, so safety is covered. The description adds rich behavioral details: conditions for compatibility_warning, temporal_alignment semantics, skipped_cross_type/subtype meaning, and a caveat that most pre-mapped topics return warnings. This goes well beyond the annotations.

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

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

The description is long but well-organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, but it could be tightened without losing important caveats.

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

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

Despite lacking an output schema, the description thoroughly explains the response: leg-by-leg prices, top_spreads_pp, compatibility_warning with concrete examples, temporal_alignment, and skipped-counters. It also sets expectations about real-world tradeability, making it complete for a tool of 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?

With 100% schema coverage, the baseline is 3, but the description adds meaning by explaining the two modes: topic auto-fetches events on each venue, and explicit ticker/slug override the mapped sides. It clarifies parameter relationships, though the interaction when mixing topic with overrides could be slightly more explicit.

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: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses a specific verb+resource ('Cross-venue spread') and distinguishes itself from sibling tools (e.g., polymarket_arbitrage) by explicitly focusing on the Kalshi–Polymarket pair and explaining modes.

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

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

It provides explicit usage modes (topic shortcuts vs explicit ticker/slug pairings) and strong warnings about when results are unreliable (compatibility_warning, temporal misalignment, 'pre-mapped ≠ tradeable'). However, it does not explicitly name alternative tools for different scenarios, so it falls short of a 5.

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

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

With readOnlyHint and idempotentHint annotations already covering safety, the description adds valuable context about scoping ('anonymous IP, BYO key hash, or account ID') and explains the list behavior when no key is given. It does not mention edge cases like missing keys, but the annotation coverage lowers the bar.

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

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

The description is front-loaded with the main action, and each subsequent sentence adds unique value: use case, scoping, and relationship to sibling tools. Despite being slightly longer than a minimal description, every sentence earns its place and there is no wasted wording.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description is complete. It covers the two modes (get by key, list all), explains the scoping model, and provides usage context. Combined with the rich annotations, an agent has all necessary information to select and invoke the tool correctly.

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

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

The schema fully documents the single 'key' parameter (100% coverage), so the description adds little beyond what's in the schema. The examples of key contents ('user's target ticker, an address, prior research notes') are illustrative, but not necessary for understanding the parameter itself.

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 ('retrieve') and resource ('value previously saved via remember'), and clearly distinguishes the list-all-keys behavior when the key is omitted. This is precise and differentiates from sibling tools like remember 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?

It explicitly tells when to use the tool ('look up context the agent stored earlier... without re-deriving it from scratch') and names the complementary tools for saving and deleting ('Pair with remember to save, forget to delete'). This serves as both positive and negative 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes further by revealing the mark_read side effect that advances the feed, describing the return payload (source, citation_uri, raw event payload), and noting the feed is persisted. This adds meaningful behavioral context beyond what annotations provide, though it doesn't cover auth or rate limits.

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

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

Three sentences efficiently deliver the core purpose, return details, filtering, stateful behavior, and polling advice. It is front-loaded with the main verb and resource, and every sentence earns its place without verbosity.

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 appropriately summarizes the return payload. It covers filtering, mark_read side effects, and polling suitability. Combined with the 100% schema coverage for parameters, it gives a complete picture of how to use the tool, though it leaves potential error conditions and rate limits undisclosed.

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 each parameter has a clear description. The description adds value by providing a concrete example for type ("sec_8k"), clarifying since as an ISO timestamp, and explaining the practical consequence of mark_read (next call only shows newer events). It doesn't add material meaning for limit or unread_only, but the schema already handles those well.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource pairing. It then clarifies it returns alerts the evaluator has written, distinguishing it from sibling tools like list_subscriptions (which manages subscriptions) and recent_changes (which tracks other changes). The purpose is unmistakable.

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

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

The description indicates when to use it (to retrieve alerts from a subscription feed) and states polling is fine, even suggesting an alternative HTTP endpoint for scripts/dashboards. It does not explicitly name sibling alternatives, but the context clearly implies this is the tool for reading fired events, while siblings like list_subscriptions serve different purposes.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable behavioral context: source-specific fallback mechanics, a USPTO soft-fail due to PatentsView sunset, and the return structure (changes[], total_changes, pipeworx:// citation URIs). No contradiction with annotations.

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

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

The description is dense yet well-structured: it front-loads trigger phrases, then explains sources, supported formats, return values, and alternatives. Every sentence earns its place, with no filler or 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?

Despite having no output schema, the description specifies return grouping, total count, and citation URIs, plus fallback and sunset behavior. It covers the complexity of a multi-source fan-out and gives an explicit alternative for static profiles, making it sufficient for a complex tool.

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

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

Schema coverage is 100%, so the schema already documents all three params. The description adds practical guidance (relative shorthand examples, 'Use 30d or 1m for typical monitoring', ticker vs CIK) that enriches schema understanding without fundamentally transforming it.

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

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

The description clearly identifies a change-feed tool for companies over a date window, with natural-language triggers and explicit fan-out to SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from the sibling entity_profile tool by contrasting dynamic changes with a static profile.

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

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

It provides explicit when-to-use signals via example queries ('What's new...') and a direct alternative: 'Use entity_profile instead when you want the static profile...' It also documents fallback behavior (GDELT→GNews) and accepted input formats, giving clear invocation guidance.

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

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

Annotations cover idempotency and non-destructiveness, but the description adds crucial context about scope (by identifier), persistence differences (authenticated vs. anonymous 24-hour retention), and the key-value storage format. This goes beyond the annotations, though it stops short of specifying overwrite semantics 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?

Three sentences, front-loaded with the main purpose, and each sentence adds distinct value: what it does, when to use it, and how it stores data. No filler or redundancy.

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

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

For a simple two-parameter tool with no output schema and helpful annotations, the description covers all essential aspects: functionality, usage triggers, persistence behavior, and tool relationships. It is complete and self-sufficient for an agent to select and use it correctly.

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

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

Schema already provides 100% parameter coverage with descriptions, so baseline is 3. However, the tool description adds meaning by explaining the key-value pairing and 'scoped by your identifier', which helps the agent understand how parameters interact and why uniqueness matters. The example keys ('subject_property', 'target_ticker') further clarify expected 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 clearly states the tool 'Save data the agent will need to reuse later', with a specific verb and resource (memory). It distinguishes itself from siblings by explicitly mentioning pairing with 'recall' and 'forget', making its role in the persistent-memory lifecycle 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?

Provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') and names complementary tools ('Pair with recall to retrieve later, forget to delete'), which frames the correct context for usage versus alternatives.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It discloses that LEI/FIGI enrichment degrades gracefully, that unresolved identifiers are listed explicitly under 'unresolved', and that each call cascades through multiple endpoints. No contradiction with annotations.

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

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

The description is dense and contains a lot of useful information, but it is structured as a single paragraph without clear separation of sections. It could be more concise or formatted (e.g., bullet points for supported types) to improve quick scanning. Still, it is not excessively long and front-loads key usage examples.

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 no output schema, the description adequately explains what identifiers are returned and how they are labelled by source, including handling of unresolved items. It covers graceful degradation and the multi-endpoint cascade. It does not explicitly describe the output structure in detail, but the provided context is sufficient for agent understanding.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by listing acceptable inputs for each type (e.g., ticker, CIK, ISIN for company) and providing an example of ISIN resolution via GLEIF. This extra context helps the agent understand parameter usage better than schema alone.

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

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

The description clearly states that the tool resolves user-spoken names to canonical/official identifiers, with specific example queries and supported entity types (company, drug). It distinguishes itself by noting it replaces 2-3 manual lookups, which helps the agent understand its unique value among siblings.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' The description also details what each entity type accepts as input and notes graceful degradation. It does not explicitly state when not to use the tool, but the context is clear enough for appropriate selection.

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, and non-destructive behavior, so the safety profile is covered. The description adds valuable context about the internal process: 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and describes output fields ('score, confidence, signal density'). This goes beyond annotations without contradicting them.

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

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

The description is concise, with two sentences that front-load the core purpose and provide a concrete use case and output summary. Every sentence adds value, with no redundant repetition of schema or annotations.

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 (multi-entity comparison, optional models and API key), the description covers the purpose, process, use case, and return values. The schema handles parameter details, and the description fills in the behavioral and output context. It lacks explicit mention of models or API key behavior, but those are documented in the schema, so it is sufficiently 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?

The schema provides 100% coverage with descriptions for all four parameters, so the baseline is 3. The description reinforces the entities parameter by explaining 'your brand + N competitors' and mentions the probing mechanism, but it does not add new details beyond the schema. It is adequate but not additive.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'Compare', the resource 'AI visibility', and the multi-entity scope, which distinguishes it from the sibling tool ai_visibility_check that focuses on a single entity. It also details the workflow (probe, rank, surface) and output, leaving no ambiguity.

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 clear use case: 'Useful for competitive AI-marketing audits' and offers an illustrative example question. It implies this tool is for comparative scenarios, contrasting with single-entity checks, but does not explicitly state when not to use it or name alternatives. This is strong contextual guidance, though missing explicit exclusions.

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, so the safety profile is clear. The description goes beyond annotations by disclosing partial failure behavior (bundlephobia first measurement can take 5-30s, sources_failed lists timeouts), the non-atomic nature across sources, and the exact return summary fields. This adds significant behavioral context beyond the structured 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, with a clear progression: purpose, usage triggers, return fields, ecosystem scope, and failure modes. Every sentence contributes unique value for a composite tool. It is not overly verbose given the complexity, though it could be tightened slightly without losing critical 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?

With no output schema, the description carries the full burden of explaining the return payload, and it does so thoroughly: it lists the summary fields, per-advisory details, links, and alternative versions. It also covers timeout behavior, partial failures, and ecosystem limitations. For a tool of this complexity, the description is remarkably complete.

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

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

Schema description coverage is 100%, with both 'package' and 'version' well-documented in the schema. The description adds marginal value by framing 'version' as optional and defaulting to latest, and by mentioning scoped packages, but this is largely redundant with the schema. The description doesn't add deeper parameter-level semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it is a composite check for 'should I add this npm package' and explicitly lists the data sources (deps.dev, bundlephobia) and the decision context. It distinguishes itself from siblings by being the only npm package evaluation tool, with a specific verb and resource ('scan' + 'dependency').

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 trigger conditions ('whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"') and also gives an explicit exclusion/alternative for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This is excellent guidance for tool selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable behavioral context by specifying the return format (company names and CIK numbers) and the tool's role in the workflow, which goes beyond the structured 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 two sentences, front-loaded with the action and resource. The first sentence states what the tool does; the second explains the output and workflow context. Every word contributes value, with no redundancy or filler.

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

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

For a simple single-parameter tool with rich annotations and an output schema, the description is sufficiently complete. It covers the purpose, input type, output, and the critical workflow context (CIK needed for other SEC tools), enabling an agent to select and invoke the tool correctly without additional information.

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

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

The input schema provides a comprehensive description of the single 'query' parameter, including examples ("Apple", "TSLA"), covering 100% of parameters. The description's mention of 'name or ticker symbol' essentially restates the schema, adding no additional parameter nuance, so the 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 action ('Search SEC EDGAR'), the resource (companies), and the input type (name or ticker symbol). It also describes the output (company names and CIK numbers) and explicitly connects this to other SEC tools, which distinguishes it from siblings that consume CIK numbers.

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

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

The description implies the primary use case by noting that CIK numbers are 'needed for other SEC tools,' establishing this as the entry point for SEC data retrieval. It does not explicitly name alternative tools or state exclusions, but the context is clear given the sibling tool names like get_company_facts and get_company_filings.

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: it details the internal mechanics (BGE-base-en embeddings, cosine over 500-char overlapping windows), the truncation cap at 200K chars with flagging, and the output structure (character offsets and similarity scores). Since annotations already cover read-only safety, this added depth is highly valuable.

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

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

The description is three sentences, front-loaded with the core action, followed by usage guidance and technical details. Every sentence adds new information—purpose, value proposition, and caveats—without repetition or fluff.

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

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

Despite lacking an output schema, the description fully prepares the agent by explaining the return format (passages with offsets and scores), the ideal use case, the truncation behavior, and the recommended workflow with a sibling tool. It covers all necessary operational details 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?

The schema covers 100% of parameters, so the baseline is 3. The description adds meaningful context beyond the schema by giving concrete examples for 'text' (SEC 10-K body, article, long tool result) and noting that longer inputs are truncated and flagged. This adds practical semantics not in the schema, earning a 4.

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

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

The description uses a specific verb and resource: 'Semantic search INSIDE a fetched record' with the return of 'top-N passages with character offsets and similarity scores.' It clearly distinguishes from sibling tools like search_companies and explicitly connects to ask_pipeworx_grounded, making the tool's role unambiguous.

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

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

It provides explicit usage context: 'Use when the record is too big to cram into the prompt' and describes a pairing with ask_pipeworx_grounded for a two-step workflow. It also explains the benefit (saves context, returns only relevant passages) without needing to formally list 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 adds substantial behavioral context beyond the annotations: it states the return value (new subscription id), the auth requirement, that anonymous/BYO cannot persist, the always-on feed behavior, SMS verification and cap, and the ability to pull alerts via recent_alerts. This goes far beyond the readOnlyHint/idempotentHint annotations and fully discloses operational traits.

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

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

The description is moderately long but densely packed with essential information. It is front-loaded with the main purpose, followed by auth requirement, supported types, and delivery channels. The structure is logical and mostly concise, though the delivery section is lengthy and could be more compact without losing key details.

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

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

For a tool with 3 parameters and nested objects, the description covers the return value, auth prerequisites, supported types, and delivery options. It omits webhook in the main text, but the schema fully documents it. The description is complete enough for an agent to correctly select and invoke the tool, with the schema filling in the remaining parameter details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description gives examples for sec_8k, polymarket_edge, and fred_series, but these closely mirror the detailed schema descriptions for the 'params' property. The delivery channels are also described similarly to the schema. Thus, the description does not add significant semantic value beyond the structured 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 primary action with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by explicitly focusing on the creation action. The supported subscription types and delivery channels further clarify its scope.

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

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

The description provides context on when to use the tool (for proactive monitoring) and notes an important prerequisite (requires a Pipeworx OAuth account). It also hints at an alternative for non-persistent retrieval via 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json', though it doesn't explicitly name sibling tools as alternatives. This is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: it returns category-bucketed examples drawn from a live catalog, includes tool+argument shapes, and supports optional topic filtering. It doesn't contradict annotations.

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

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

The description is longer than average, but every portion earns its place: user-phrasing examples, the purpose, return value, usage variants, and explicit first-use guidance. It is front-loaded with natural-language queries and organized with em-dashes and parentheticals. Slightly dense 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?

Despite having no output schema, the description explains what the tool returns (category-bucketed example questions with exact tool+argument shape), how to call it (no args vs topic), and when to use it. Given the light schema and strong annotations, this is sufficient and complete for an agent to select and invoke the tool correctly.

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

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

The schema already documents the single optional topic parameter with 100% coverage. The description adds extra semantic value by giving example values ("finance", "pharma", "betting") and clarifying the behavior difference between omitting and providing the topic — omit for a cross-category spread, pass topic to focus. This goes slightly 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's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It also distinguishes itself from sibling tools by explicitly noting it should be used FIRST and that it teaches how to call meta-tools like ask_pipeworx and entity_profile.

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

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

The description gives explicit usage guidance: call with no arguments for the full spread, pass topic to focus, and use FIRST when you don't know what Pipeworx can do. It also points to alternatives (meta-tools) and lists concrete example topics, making when-to-use unmistakable.

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 meaningful context beyond the annotations: ownership enforcement, deactivation rather than deletion, and historical events remaining available via recent_alerts. These details are not captured in the annotations and provide useful behavioral 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 two sentences, front-loaded with the core action. Every phrase adds value: ownership, deactivation, and historical availability. There is no unnecessary verbosity.

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

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

The tool is simple (one parameter), and the description covers key aspects: cancellation, ownership, deactivation, and historical availability. The lack of output schema and return value explanation is a minor gap, but given the low complexity, the description is largely 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?

The schema already fully describes the id parameter (coverage 100%), noting it is returned by subscribe. The description only says 'by id,' adding no new meaning, so it meets the baseline of 3.

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

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

The description opens with 'Cancel a subscription by id,' which is a specific verb and resource. It clearly distinguishes this tool from siblings like subscribe and list_subscriptions by the action, and the mention of deactivation further clarifies the exact effect.

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

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

The description clearly states the tool cancels a subscription and imposes an ownership constraint ('you can only cancel your own subscriptions'), which informs when to use it. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so it falls short of a 5.

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

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

Annotations declare readOnly/openWorld/idempotent, but the description adds critical behavioral nuances: the distinction between two processing paths, exact percent-delta math for company financials, and the crucial semantics of 'could_not_verify' vs 'unsupported'. It explicitly instructs that 'could_not_verify' must not be treated as evidence, which is valuable beyond structured annotations.

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

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

The description is dense but every sentence contributes: trigger phrases, verification paths, verdict list, error semantics, and efficiency note. It is front-loaded with usage signals and avoids redundancy. Though long, it is appropriately sized for the tool's complexity and contains no filler.

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

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

With no output schema, the description fully covers return values (verdict, actual value, citation, reasoning) and error behavior. It also covers parameter semantics, usage scenarios, and distinguishes from siblings. This is a complete standalone description that leaves no major operational questions unanswered.

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 100% of parameters, but the description enriches them meaningfully: 'tolerance_pct' is explained as overriding the claim's implied tolerance, with a specific use case (1–2 for hallucination detection) and a default cap. The 'claim' parameter is illustrated with concrete examples, adding practical guidance beyond the schema's field description.

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

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

The description opens with explicit trigger phrases and states a specific function: natural-language claim verification against authoritative sources. It clearly distinguishes the tool from siblings by detailing the two verification paths (SEC EDGAR XBRL fast path for company financials, grounded pipeline for all other claims) and mentions it replaces 4–6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives trigger phrases. It also clarifies the scope (company-financial vs any other claim) but does not explicitly name when-not-to-use alternatives like ask_pipeworx or deep_research, so it lacks direct exclusion/sibling comparison.

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