animequotes

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

With annotations already declaring readOnly/openWorld/idempotent, the description adds valuable context: the default model and cost implication ('you pay Anthropic directly'), the return shape (per-model {score, confidence, signals, raw_response} + combined view), and that _apiKey passes straight through. This goes beyond what annotations convey.

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

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

The description is three sentences, front-loading the core function, then covering configuration/cost, return format, and use cases. No filler or redundant restatement of the tool name; every sentence contributes new 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?

For a read-only, 4-parameter probe tool with no output schema, the description covers the essentials: purpose, default behavior, optional customization, response shape, and typical use cases. Minor gaps like error handling or what happens if the passed key is invalid are not addressed, but the overall picture is solid.

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 semantic meaning beyond the schema: it clarifies that omitting 'models' defaults to the free workers-ai model, explains the role of _apiKey as a BYO Anthropic key, and implicitly describes how parameters interact. This elevates it above the baseline.

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

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

The description opens with a specific verb ('Probe') and a clear resource ('one or more LLMs'), then explains the output (visibility score 0-100 per model). It also differentiates from siblings by focusing on any entity's AI visibility, unlike tools like ask_pipeworx or scan_competitor_ai_presence, and lists concrete use cases.

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

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

The description provides explicit use contexts ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to extend with _apiKey. However, it does not mention any alternatives or when not to use this tool, so it stops short of full exclusionary guidance.

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

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

Annotations already declare read-only/idempotent behavior. The description adds valuable internal behavior: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs'. It also notes speed ('one fast call') and tier availability, which goes beyond the annotations.

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

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

The description is long but well-structured: it opens with a directive, lists covered domains, explains the routing mechanism, gives triggers, examples, and alternatives. Every sentence carries actionable information, though its length is on the higher side.

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

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

For a complex meta-tool, it covers what it does, when to use it, examples, output format (structured answer with citations), and how it compares to alternatives. It does not mention error handling or failure cases, but these are not critical to invocation. Given the absence of an output schema, it adequately explains the return type.

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

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

Input schema has 100% description coverage for all six parameters, all described as aliases for the `question` string. The description doesn't add parameter-specific syntax, but it provides usage examples that model question phrasing. Baseline 3 is appropriate since 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 states the tool answers factual questions by routing to thousands of sources and returns structured answers with citations. It uses specific verbs like 'PREFER OVER WEB SEARCH' and 'Routes the question', and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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?

Extensive guidance is provided: 'START HERE for most questions', with concrete trigger phrases ('what is', 'look up', 'find') and examples. It also gives explicit alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description adds critical behavioral context: it is a full working router, not a fallback stub, and it currently matches ask_pipeworx exactly because no candidate is active. It also discloses that candidate routing improvements are enabled live during tests, which is important for setting expectations about variability. 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 four sentences and somewhat detailed, but every sentence adds value: what it is, current status, usage guidance, and an important clarification about not being a fallback. It is front-loaded with the core identity as a beta router. Slight verbosity around the retirement date could be trimmed, but it does not harm clarity.

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 (a universal router over 5,529 tools), the description provides sufficient context: same arguments, same response shape, current equivalence to ask_pipeworx, and the experimental purpose. The absence of an output schema is mitigated by stating 'same response shape.' It does not provide examples, but the aliases are already in the schema, so this seems complete enough for a beta variant.

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 100% coverage, documenting the 'question' parameter and all aliases (q, text, input, query, prompt) with descriptions. The description only says 'same arguments' without adding any new semantic detail. Per the baseline for high schema coverage, a 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 identifies this as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and response shape. It distinguishes itself from the sibling ask_pipeworx by being the experimental edge with candidate routing improvements. The verb 'ask' and resource 'pipeworx' are explicit, and the relationship to the stable tool is unambiguous.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing,' providing direct guidance on when to choose this tool. It also explains that results are compared against the stable router, implying ask_pipeworx as the stable alternative. It lacks an explicit 'do not use when' statement, 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?

Goes well beyond the readOnlyHint and idempotentHint annotations by detailing the exact return structure (success and refusal), the list of possible refusal_reason values, and the extra LLM call cost. No contradiction with the annotations; the openWorldHint aligns with the no-invention policy.

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

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

The description is a single dense paragraph, but it is well-organized with a clear progression: what it does, return format, when to use, and cost. Every sentence adds value, though the listing of refusal reasons could have been a bit more structured. Still, it is appropriately concise for the complexity.

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

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

The description is fully self-contained: it explains the routing mechanism, the return payload, all refusal scenarios, the use cases, and the cost trade-off. Since there is no output schema, this textual description fully compensates and enables an agent to understand the tool's behavior completely.

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

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

The schema already covers all 6 parameters (aliases for question) with 100% description coverage, so the baseline is 3. The description adds context that the tool auto-fills underlying tool arguments, but does not need to explain parameter syntax further. It provides just enough context beyond the schema.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode that extracts answers only from tool results. It distinguishes itself from ask_pipeworx by emphasizing the grounded extraction step and the explicit refusal behavior, making its purpose unambiguous.

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

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

Provides explicit guidance on when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including the cost trade-off. This is exactly the kind of contextual decision-making support an agent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description goes far beyond this by detailing actual behavior: resolver contract with match confidence/scores/alternatives/suggestions, low-confidence blocking via status:'low_confidence_match', handling of closed/dead markets, wide-spread tradeability flags, news fallback fields (_fallback_attempted, retry_after_sec), and cancellation-rule parsing with EV implications. 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 clearly labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) that make it scannable. It front-loads the central purpose and input formats. While some detail could be trimmed, it is dense and non-redundant for a tool with complex output behavior.

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

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

With no output schema, this description carries the full burden of explaining responses and edge cases. It thoroughly covers response shapes (market, analysis, evidence), resolver contracts, parent-event extraction, news fallback behavior, safety statuses, and cancellation-rule risk. This is a complete guide for an agent to use the tool safely and interpret results 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% for all three parameters, and the schema's descriptions are already clear (e.g., market accepts slug, URL, or question text). The tool description repeats these input formats and adds examples, but it does not explain the depth parameter beyond what the enum states, nor does it add additional parameter-level semantics. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input types (slug, URL, question text), the resolution/classification/fan-out pipeline, and differentiates from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on evidence gathering and market-vs-model comparison.

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

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

The description explicitly lists use cases: '"should I bet on X", "what does the data say about Y", or "is there edge in Z"' and provides rich fan-out examples. It also advises checking resolver confidence and cancellation rules before sizing bets. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already mark readOnly/openWorld/idempotent/non-destructive, so the bar is lower, but the description adds substantial context: it names data sources (SEC EDGAR/XBRL, FAERS), mentions off-calendar fiscal year handling, result sorting by primary metric, and citation URI returns. It does not contradict annotations.

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

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

The description is longer than strictly necessary, but every sentence adds value: trigger phrases, type-specific data sources, and the efficiency benefit. The opening is slightly front-loaded with a long list of example phrases, but it's still well-organized and free of filler.

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

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

Given the absence of an output schema, the description tells the agent what to expect ('paired data + pipeworx:// citation URIs per entity'), the scope (2–5 entities), and the key handling behavior (off-calendar fiscal years). This is sufficient 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?

Although schema covers both parameters, the description explains what each enum value actually returns: 'company' pulls 10-K revenue/net income/cash/long-term debt, while 'drug' pulls FAERS counts, FDA approvals, and trials. It also clarifies values accept tickers/CIKs or drug names, adding meaning beyond the schema's terse descriptions.

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

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

The description immediately defines side-by-side comparison of 2–5 companies or drugs in one parallel call, with a clear verb ('compare') and resource scope. It also distinguishes itself from sequential single-entity lookups, which separates it from siblings like 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?

It lists concrete trigger phrases ('Compare X and Y', 'X vs Y', 'rank these companies') and explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This gives clear when-to-use guidance and names the alternative to avoid, satisfying the dimension.

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 openWorldHint=true, but the description adds critical behavioral context: account/sign-in requirements, the decomposition into parallel facet routing across 5,529 tools, the precise output schema (evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), latency expectations, and the guarantee that gaps[] are explicit (never invented). It also clarifies citation_uri is only present when fetchable, avoiding false expectations.

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

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

The description is lengthy but information-dense, covering account prerequisites, usage guidance, tool behavior, output details, and latency. Some redundancy exists (e.g., the non-open-web warning appears twice), but the structure is logical and front-loaded with the critical account/alternative-tool requirement.

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 specifies the return packet format including verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It also addresses latency, semantic excerpting, and account tiers, leaving no major operational question unanswered for an agent deciding to invoke this tool.

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

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

The schema already documents both parameters with high coverage, but the description deepens semantics: it explains depth levels ('quick' single hop, 'standard' with gap recovery, 'thorough' with iterative hop) beyond the enum strings, and clarifies the question parameter accepts broad/multi-part questions because decomposition is the point.

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 deep_research as a grounded multi-source research tool over structured data, with a specific verb ('researches') and resource ('Pipeworx's 1455 structured data sources'). It distinguishes from siblings like ask_pipeworx by stating 'this is NOT open-web search' and noting it's for broad/multi-part questions, whereas ask_pipeworx is for single lookup.

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

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

The description explicitly states when to use it ('Best for broad/multi-part questions over structured data') and when to use alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also provides an account-based condition, directing unsigned-in users to ask_pipeworx.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds valuable behavioral context beyond annotations: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are 'ready to call directly, no second schema lookup needed.' This discloses output format and reduces ambiguity about what the agent will receive.

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 ('Find tools by describing the data or task'). The domain list is a single clause, and the return behavior and usage guidance each get their own sentence. Every sentence earns its place 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?

Given the tool's complexity as a meta-discovery tool with many siblings, the description covers purpose, usage timing, return value, and query scope. It even mentions that results include full input schemas, eliminating the need for a second lookup. No output schema exists, but the description sufficiently explains what the tool returns and how to invoke it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic value by listing the domains the query parameter can target (SEC filings, FDA drugs, FRED economic data, etc.), which helps the agent formulate a natural language query. It also emphasizes 'describing the data or task,' reinforcing the free-form nature of the query parameter.

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

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

The description begins with a specific verb and resource: 'Find tools by describing the data or task.' It clearly states the tool's function (discovering tools) and distinguishes it from siblings by listing many domains it covers. The phrase 'Call this FIRST' also positions it as a meta-tool, differentiating it from the task-specific 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?

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance. It implies when-not-to-use via 'not just one answer' but does not name specific alternative tools, so it lacks an explicit exclusion.

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

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

Even with annotations indicating read-only/idempotent behavior, the description adds significant context: parallel fan-out across SEC, XBRL, USPTO, GDELT/GNews, GLEIF; detailed return fields; patents API sunset and soft-fail behavior; GDELT→GNews fallback; input restrictions (zero-padded CIK, no names). 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 lengthy but packed with useful examples and structured sections: user-phrase exemplars, fan-out sources, return field list, and parameter constraints. Every sentence contributes to selection and invocation; the length is justified 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?

No output schema exists, so the description fully covers return values (cik, recent_filings with URIs, fundamentals, patents, news, LEI), explains failure modes (patents sunset, soft-fail), and documents input constraints. This is complete for an AI agent to invoke 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% with both parameters fully described, including examples and the name-not-supported caveat. The description repeats these examples ('AAPL', '0000320193') but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses specific verbs ('profile', 'brief me on') and clearly defines the resource (US public company) and output (full cross-source profile). It distinguishes from siblings by explicitly stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and by mentioning resolve_entity for name-only inputs, setting clear boundaries.

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

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

It gives explicit when-to-use guidance ('when the user asks for a holistic view'), when-not-to-use (names not supported), and names the alternative (resolve_entity). It also instructs to prefer this over chaining single-pack lookups, providing clear decision rules.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description does not contradict these. It adds contextual value by noting the memory was 'saved earlier' and that it can clear 'sensitive data,' which reinforces the irreversible nature. It doesn't discuss missing-key behavior or return values, but given the annotations, 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?

The description is exactly two sentences, front-loaded with the action, and every word contributes. It avoids fluff or repetition while covering purpose, usage, and sibling context.

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

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

For a single-parameter tool with no output schema and strong annotations, the description is complete. It explains the operation, when to use it, and how it relates to related tools, giving the agent all necessary context to invoke it correctly.

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

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

The input schema covers 100% of the single parameter with 'Memory key to delete.' The description adds 'by key' and 'previously stored,' but these merely restate the schema rather than providing additional semantic details about format, constraints, or behavior. Baseline of 3 is appropriate 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 opens with 'Delete a previously stored memory by key,' which uses a specific verb and resource, exactly stating the operation. It clearly distinguishes from siblings like 'remember' and 'recall' by its explicit pairing and the 'previously stored' qualifier.

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

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

The description provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names companion tools 'remember' and 'recall,' which helps an agent choose among related memory operations.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds process transparency ('Fetches the page, extracts title/description/key links') and clarifies the output ('single text blob ready to drop at site-root/llms.txt'), which is meaningful context beyond the annotation defaults. It does not cover edge cases like invalid URLs, but the provided information is sufficient for a read-only generation tool.

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 concise sentences. The first states the main action and benefit, the second explains the process and output format, and the third lists concrete use cases. Every sentence earns its place with no redundancy or irrelevant details, making it easy to parse quickly.

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

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

For a simple tool with 2 parameters and no output schema, the description is complete. It explains the input (any URL), the process (fetch, extract, emit), the output format (standard llms.txt markdown), and the intended use cases. The annotations cover safety and idempotency, so the agent has all necessary context to invoke the tool correctly.

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

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

Schema description coverage is 100%, so both parameters (url and max_links) are already well-documented with examples and defaults. The description does not add parameter-specific semantics beyond what the schema provides; it mentions 'any URL' but that is implicit in the schema. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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

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

The description opens with a specific action ('Generate a production-ready llms.txt file') and clearly identifies the resource (any URL) and output format (standard llms.txt markdown). It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning, and the use cases (client sites, own projects, competitor auditing) clarify the scope.

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

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

The description provides explicit use cases in the 'Useful for' list, which helps an agent decide when to invoke the tool. However, it does not explicitly mention alternatives or when NOT to use it, leaving some ambiguity around the competitor-auditing use case that overlaps with sibling tools like scan_competitor_ai_presence.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that only active subscriptions are returned by default and includes the option to include inactive. It also enumerates the response fields, which is useful behavioral context beyond the annotations.

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

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

Two sentences, front-loaded with the core purpose, followed by return fields and usage guidance. Every sentence earns its place with no redundancy 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?

With one optional parameter, no output schema, and strong annotations, the description provides the necessary return fields and default filtering behavior. It fully equips the agent to decide when and how to invoke the tool.

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

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

The single parameter include_inactive is already fully described in the schema ('Include cancelled subscriptions in the response (default false)'). With 100% schema coverage, the description adds little parameter-level value beyond reinforcing the default behavior.

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

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

The description states 'List the caller's active subscriptions' with a specific verb, resource, and scope. It also names the exact fields returned (id, type, params, created_at, last_fired_at, fire_count), clearly distinguishing it from sibling tools like subscribe/unsubscribe by referencing the purpose of reviewing before adding or canceling.

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

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

Provides clear 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 relative to subscribe/unsubscribe, though it does not explicitly name alternatives or state when not to use.

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

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

Annotations provide no behavioral hints (all false), so the description carries full burden. It discloses rate limiting (5 per identifier per day), cost (free, doesn't count against quota), the claim_token workflow for follow-up, and that the team reads digests daily. This goes well beyond what annotations offer and gives the agent important non-obvious context.

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

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

The description is longer than the calibration exemplar but every sentence serves a distinct purpose: scope, use cases, exclusions, follow-up mechanism, rate limits, and cost. It is front-loaded with the core action and progressively adds necessary context. Could be slightly tightened, but it remains efficient for the complexity it covers.

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 4 params, all optional, nested objects, and no output schema, the description compensates by explaining the return flow (claim_token and later status reading), what to include, what not to include, rate limits, and cost. It leaves no critical gaps for an agent trying to decide when and how to invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token workflow ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which clarifies parameter purpose beyond schema text. It also contextualizes how to structure feedback, though it doesn't deeply elaborate each parameter.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific scenarios (bug, feature/data_gap, praise) and explicitly scopes to tools served by this Pipeworx connection, distinguishing it from other feedback channels. This is a specific verb+resource with clear 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 explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions: 'if the tool came from a different MCP server... file it with that server instead,' plus what to avoid ('don't paste the end-user's prompt'). This is comprehensive 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?

With annotations already indicating a safe read-only operation, the description adds meaningful context: data is self-aggregated from CF analytics-engine, contains no PII, and is cached for 5 min to 1 hour depending on the window. This discloses important behavioral traits (privacy and staleness) 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 well-structured and front-loaded with the core function, followed by bulleted use cases and a brief behavioral note. Each sentence contributes value, with no 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?

For a simple tool with one optional parameter and no output schema, the description sufficiently explains the returned data ('(pack, tool, count)'), the time windows, caching behavior, and use cases. It gives an agent enough to invoke and interpret results without ambiguity.

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

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

The input schema already provides full coverage (100%) with a detailed description of the 'window' parameter, including default and trade-offs. The tool description only mentions the valid windows without adding new semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns trending call data on Pipeworx, specifying outputs ('top tools, top packs, and total call volume') and a time window. It distinguishes itself from sibling tools like discover_tools by focusing on aggregated usage signals rather than general 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 description explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tools, and checking alignment with agent needs. However, it does not mention when not to use the tool or name alternatives, falling just short of the highest bar.

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?

Despite annotations already declaring readOnly/openWorld/idempotent, the description adds key behavioral details: the >3pp threshold for emitting signals, the Jaccard similarity ≥0.30 semantic anchor, placeholder fragmentation filter, and the fill check semantics including 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.'

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 long, but organized with ALL-CAPS section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that help navigation. Some details like exact thresholds are necessary for correct usage, though the text could be trimmed to improve scannability.

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

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

Even without an output schema, the description lists the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, etc.) and the fill_check derived metrics (theoretical vs realizable edge, thin_legs). It also covers edge cases (low similarity, placeholders, null arb signal), making it complete enough 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 already describes the two params, but the description enriches them with concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and explains the internal chains: event walks child markets and computes partition_check; topic searches related events and flattens unions. It also notes cross-event catches date patterns that single-event misses.

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

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

Description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection through monotonicity and partition-sum analysis.

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

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

Provides explicit mode selection: 'Call with NO args for a trending_scan...', 'pass event...', 'or topic...'. It also recommends event for a specific market, topic for cross-event scanning, and points to polymarket_fill_risk for custom sizing, giving clear when-to-use guidance.

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

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

Even though annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds rich behavioral detail beyond them: KV-level caching (1h), computation of edge_pp_net after slippage, the 24h-move warning, model-family specifics (lognormal barrier, GDELT ratio), and diagnostics counters that explain empty segments. This far exceeds the annotation baseline and provides actionable insight into the tool's 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?

The description is exceptionally long and dense, with many technical details (per-sport alpha values, gate relaxations like 'Run 8 from prior 85%/5%/50:1') that may be unnecessary for tool invocation. While it is front-loaded with a clear purpose, the volume of information could overwhelm an agent. It is appropriately sized for a complex tool, but a leaner version would be more concise.

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 9 parameters and no output schema, yet the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), edge computation, filtering behavior, and why segments may be empty. It also covers edge cases like placeholder slugs and the unreliability of the Fed signal. This is a complete contextual picture for an agent to invoke the tool 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?

The input schema covers all 9 parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful context: it explains why min_kelly doesn't filter partition arbs (basket trades don't compose to single-leg Kelly), the rationale for slippage defaults, and the effect of knobs like min_liquidity and max_spread_pp. This extra layer helps agents reason about parameter choices.

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

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

The description opens with a precise verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes this from sibling tools like polymarket_arbitrage (which finds cross-market arbitrage) and polymarket_edge_tracker (which tracks edges over time), making the tool's unique function 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?

The description explicitly states its intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides caveats (e.g., Fed signal reliability, 24h-move warning) and explains how to use knobs like min_liquidity and max_spread_pp to filter for tradeable edges. It does not explicitly name alternative tools, but the context is sufficient to guide 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 readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond this by explaining response structure (tracked[], expired[], snapshot_dates[]), the meaning of edge_pp_net sign, how expired opportunities are handled, snapshot gaps, and the 60-day TTL limit. This is rich behavioral disclosure that significantly aids agent understanding.

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

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

The description is well-organized with labeled sections (Args, RESPONSE, LIMITS). Every sentence carries crucial information—edge sign, expiration behavior, snapshot gaps, TTL boundaries—without fluff. It's dense but appropriately sized for 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, the description fully explains the return format and data semantics, including tracked vs. expired opportunities, trend values, decay calculation, and snapshot dates. It also covers practical limits like the 60-day TTL and daily-close basis. This is highly complete for an analytical 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%, both parameters have descriptions. The description adds only marginal context (e.g., calling window a 'snapshot family') but largely repeats what the schema already provides. The slight discrepancy between 'max 30' in description and 'clamp 2-30' in schema could cause confusion, but overall it doesn't add substantial 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 a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence ('how long has this edge existed and is it shrinking?'), not just current edges.

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

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

The description provides clear context for when the tool is valuable (comparing fresh vs. aged edges) and what question it answers. It doesn't explicitly name alternatives or exclusion criteria, but the intended use case is strongly implied and the response semantics make it obvious this is for historical analysis.

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 far beyond annotations: it explains that the tool walks the order-book ladder, returns a verdict (clean/degraded/cannot_fill), handles partial fills, and identifies forced directional risk. It also notes the basket-mode behavior of summing theoretical vs realizable values. These add rich behavioral context to the readOnly/openWorld/idempotent hints, 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 long but meticulously structured: a one-line summary, then REQUIRES/SINGLE-MARKET/BASKET sections, and a USE THIS closing. Every sentence carries task-critical detail—mode distinctions, output fields, risk warnings. No filler; the length is justified by the tool's inherent complexity.

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

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

Given two distinct operating modes and a rich set of return values (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, etc.), the description comprehensively covers both modes, their inputs, outputs, and the risk consequences of partial fills. With no output schema, the description fully enumerates return fields, and it ties the tool into the broader arb trading workflow. Absolutely complete for its context.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it defines the REQUIRES relationship between market and event, explains side defaults for both modes, clarifies size_usd as 'max spend on buys, target proceeds on sells' in single-market and 'settlement notional S' in basket mode, and even mentions clamping (10–1,000,000). This goes well beyond the schema's bare parameter lists.

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

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

The description opens with a clear, specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools by focusing on fill risk/execution viability, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to frame its role. The two modes (single-market vs basket) are clearly defined.

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 when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two distinct usage modes and interprets size_usd differently for each, giving clear context for selection. No alternatives are needed because it names the specific sibling signals it validates.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description goes far beyond by detailing compatibility_warning triggers, temporal alignment semantics, and skipped cross-type/subtype counters, which are critical behavioral traits not conveyed by annotations. This layer of transparency is exemplary.

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 appropriately structured with clear sections (modes, response, safety fields) and every sentence carries useful information. It is dense but not wasteful, though slightly verbose in the counters explanation. It earns a high score for being well-organized and front-loaded with the core purpose.

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

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

Given the tool's complexity and lack of output schema, the description fully compensates by explaining the response structure, safety fields, temporal alignment, and caveats about real spread availability. It provides all necessary context for correct invocation and interpretation.

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

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

Schema covers all three parameters at 100%, but the description adds value by enumerating the topic shortcuts and explaining the override behavior of explicit tickers. This clarifies the relationship between the parameters and the two modes, going beyond what the schema alone provides.

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

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

The description clearly states the tool's function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by focusing on cross-venue comparison and includes detailed safety fields, making its purpose unmistakably specific.

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

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

The description explains the two usage modes (topic shortcuts vs explicit tickers) and provides important context on when the tool is reliable (e.g., warning that pre-mapped topics are not necessarily tradeable and that compatibility_warning indicates no arbitrage). It does not explicitly name alternative tools, but this is not necessary given the clarity of the tool's purpose.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the crucial behavioral trait of randomness, which is not covered by annotations, and also names the returned fields. This enriches the agent's understanding beyond the structured safety hints.

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

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

The description is two short, front-loaded sentences. The first sentence states the action, and the second lists the output. Every word is purposeful, with no 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?

Given the tool's simplicity (no parameters), the presence of a rich annotation set, and the existence of an output schema (which likely documents return structures), the description is complete. It covers purpose, output, and the key behavioral nuance of randomness.

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 tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, but it doesn't add any harm. The schema is complete with an empty properties object, and the description's mention of return fields is relevant though not parameter-related.

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: 'Get a random anime quote' with a specific verb and resource, and it also lists the return fields (quote text, character name, anime series title). This distinguishes it from sibling search tools like search_by_anime and search_by_character.

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

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

The description gives clear context for when to use the tool: when a random anime quote is needed. It does not explicitly mention alternatives or exclusions, but the purpose is self-evident and the lack of parameters makes it straightforward. There is no explicit when-not guidance, but it is not misleading.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds useful context: scoping (anonymous IP, BYO key hash, or account ID), the list-all-keys behavior when omitting the key, and relationships with sibling tools. 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 three sentences, front-loaded with the core action, followed by usage and scope. There is no redundant or wasted wording; every sentence contributes essential 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?

For a simple tool with one optional parameter, the description covers what it does, when to use it, and its scoping. It does not explicitly describe the return format or error behavior, but the action words ('retrieve a value', 'list all saved keys') imply the result. Overall, complete enough for the tool's simplicity.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The tool description reinforces the omit-to-list behavior and adds scoping details, going slightly beyond the schema by giving concrete usage examples and pairing with related tools.

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

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

The first sentence clearly specifies the action ('Retrieve a value') and the resource (memory saved via remember), while also describing the alternative behavior of listing all keys when the key argument is omitted. It distinguishes itself from sibling tools by explicitly naming 'remember' and 'forget' as counterparts.

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

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

Gives a clear use case ('look up context the agent stored earlier — the user's target ticker, an address, prior research notes') and contrasts with re-deriving information. It also mentions scoping to an identifier, but does not explicitly state when not to use (e.g., for current data).

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 important behavioral traits beyond annotations: the mark_read side effect (mutating read state), the return fields (source, citation_uri, raw payload), and the feed's alternate access URL. This adds meaningful context 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 action, and every sentence adds value. It avoids repetition of schema fields and stays within appropriate 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?

For a tool with 5 optional parameters and no output schema, the description covers return format, filtering, side effects, polling suitability, and an alternate access method. This is complete given the tool's simplicity and annotation coverage.

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%, establishing a baseline of 3. The description adds examples and clarifications: 'sec_8k' for type, 'ISO timestamp' for since, and explicit note that mark_read:true changes future calls. This elevates parameter understanding beyond the schema alone.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource pair, and elaborates with return contents and filtering. It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on alerts/events from the subscription feed.

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

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

The description states 'Polls work fine' and provides an alternative HTTP endpoint, offering clear usage context. However, it doesn't explicitly compare against sibling tools or state when not to use this tool, so it stops short of a 5.

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

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

While annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds runtime behaviors not captured in annotations: one parallel call fan-out, automatic GDELT→GNews fallback, PatentsView API sunset causing soft-fail, and the exact return shape (changes[] grouped by source, total_changes, pipeworx:// URIs). This is high-value 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 dense but not bloated; it packs in query examples, source list, fallback logic, parameter formats, output shape, and an alternative tool. It could be improved with bullet points or clearer structural separation, but each sentence earns its place and the key purpose is front-loaded.

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

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

For a complex multi-source aggregator with no output schema, the description is remarkably complete. It covers the return structure, source-specific behavior, parameter semantics, fallback conditions, and a pointer to the alternative entity_profile tool. An agent could invoke this tool correctly with no additional context.

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

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

Schema coverage is 100% (all three parameters have descriptions), so baseline is 3. The description adds extra semantics: relative shorthand examples ('7d', '30d', '3m', '1y'), a recommendation for typical monitoring, and clarification that value can be ticker or zero-padded CIK. This slightly exceeds schema-level detail, meriting 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 opens with concrete query examples ('What's new with X') and clearly states it's a 'change feed for a company in the last N days/weeks/months'. It names the specific aggregated sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly contrasts with sibling entity_profile, so purpose is unambiguous and well-differentiated.

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 guidance on when to use this tool: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains source preference and fallback conditions (GDELT preferred, GNews when rate-limited/5xx), and even recommends typical 'since' values ('Use 30d or 1m for typical monitoring'). This goes far beyond a simple purpose statement.

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 idempotence and non-destructiveness. The description adds valuable context about key-value scoping by identifier, persistence differences for authenticated vs. anonymous users, and the 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

Three sentences, each earning its place: purpose, usage guidance, and persistence/sibling context. Front-loaded with the primary action, highly concise 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 two-string-parameter tool with no output schema, the description covers purpose, when to use, persistence behavior, and sibling relationships. Nothing significant is omitted for an agent to invoke this correctly.

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

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

The input schema fully describes both 'key' and 'value' with examples and types. The description echoes similar examples ('target ticker', 'address') but does not add substantial new meaning beyond the schema. Since schema coverage is 100%, 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 ('Save') and resource ('data the agent will need to reuse later'), clearly distinguishing the tool as a memory store. It explicitly mentions pairing with 'recall' and 'forget', differentiating it from sibling tools.

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

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

Provides clear when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference, a research subject') and explains how it fits with siblings ('Pair with recall to retrieve later, forget to delete'). This is explicit and actionable.

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: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, labels source origins, and explicitly reports unresolved identifiers. These details inform the agent about reliability, performance, and output formatting, which the annotations alone do not convey.

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

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

The description is well-structured with a purpose statement, usage hint, and a SUPPORTED TYPES section. It is somewhat verbose, but each sentence contributes useful information, and the front-loaded examples and 'Use FIRST' instruction make it efficient for an agent.

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 two entity types, multiple data sources, and fallback behavior, the description is remarkably complete. It covers input flexibility, output composition, source attribution, unresolved handling, and degradation behavior. No output schema exists, but the description sufficiently explains what will be returned.

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 covers parameter descriptions thoroughly (100% coverage), so the baseline is 3. The description adds extra meaning by detailing the types of accepted inputs (ticker, CIK, name; brand/generic) and what each type returns (e.g., CIK, ticker, LEI, RxCUI), going beyond the schema's basic examples.

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

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

The description clearly states the tool's purpose: resolving names to canonical identifiers required by other tools. It provides concrete example queries and explicitly mentions 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input,' which distinguishes it from sibling tools like entity_profile or compare_entities.

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 includes strong usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups and covers both company and drug types. While it doesn't explicitly list alternatives or exclusion criteria, the context is clear enough for an agent to know when to select it.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds meaningful behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses the return format (ranked list with score, confidence, signal density), providing value beyond annotations.

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

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

Three sentences: the first declares the core function, the second details the workflow and ranking, the third explains the use case and output. Every sentence earns its place 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?

With annotations covering the safety profile and schema covering all parameters, the description fills the remaining gaps: it explains the internal probing mechanism and specifies the return structure (score, confidence, signal density), which is essential given there is no output schema. Complete for a comparison tool.

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

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

Schema coverage is 100% — all four parameters are fully described in the schema, including the nuance that the first entity is treated as the subject. The description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly states a specific verb ('Compare'), resource ('AI visibility'), and scope ('across multiple entities side-by-side'). It distinguishes from the sibling ai_visibility_check by explicitly noting it probes each entity and ranks results, making it obvious this is the multi-entity comparison 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?

Explicitly mentions a use case ('competitive AI-marketing audits') and gives a concrete example query. It doesn't explicitly name alternative tools or state when not to use it, but the phrase 'across multiple entities' and the workflow of comparing against competitors clearly separates it from single-entity alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable runtime behavior: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list if it times out. This goes beyond annotations, though it doesn't cover every possible edge (e.g., rate limits), which is acceptable.

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?

A dense paragraph but every sentence contributes: purpose, use case, return fields, ecosystem scope, and failure behavior. Slightly long for a tool description, but justified given the composite nature and multiple data sources. No wasted words.

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

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

No output schema exists, so the description correctly documents the return shape, including the summary block fields, per-advisory details, links, and alternative versions. It also covers edge cases like timeouts, partial failures, and ecosystem limitations. Complete for a complex composite 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 covers both parameters with descriptions (100% coverage), including scoped package acceptance and defaulting behavior. The description doesn't add new parameter-level details beyond the schema, but it does frame the parameters within the composite use case. Baseline 3 is appropriate since the schema already handles the burden.

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

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

The description clearly identifies this as a composite npm-package evaluation tool, with specific verbs like 'check' and 'fans out', and a concrete use case ('should I add this npm package'). It distinguishes itself from sibling tools by explicitly scoping to NPM and naming deps.dev:version as the alternative for other ecosystems.

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

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

Provides explicit when-to-use guidance with concrete examples ('is X safe / popular / small', 'what does adding lodash cost me'), and an explicit alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. Also clearly notes the NPM-only scope in v1.

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 the operation as read-only, idempotent, and non-destructive. The description adds little beyond that, only restating that it returns quotes with character/series info, which is also covered by the output schema. There is no additional context about rate limits, matching behavior, or edge cases.

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

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

The description is a single, well-structured sentence that front-loads the action ('Search for quotes') and specifies the resource and output. No unnecessary words or repetition; every clause adds value.

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

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

For a simple tool with one parameter, high schema coverage, output schema present, and safety annotations, the description is sufficient. It tells the user what it does and what it returns. It lacks only explicit sibling differentiation, but that is a minor gap given the tool's simplicity.

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

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

The schema description covers the 'anime' parameter 100%, including examples. The description's example ('Attack on Titan') duplicates the schema example, so it adds no new semantic meaning. The baseline of 3 applies because the schema handles parameter documentation 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 clearly states the tool's function: 'Search for quotes from a specific anime series by title' with an example ('Attack on Titan'). It specifies the resource (anime series), the verb (search), and the output (matching quotes with character and series info), distinguishing it from sibling tools like search_by_character.

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 implicitly defines when to use this tool: when you have an anime title. It says 'by title' and includes an example, providing clear context. However, it does not explicitly mention alternatives like search_by_character for character-based searches, so it lacks 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 disclose read-only, idempotent, and non-destructive behavior. The description adds that it returns quotes with character, series, and quote text, but this is likely covered by the output schema. Minimal extra behavioral context beyond annotations.

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

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

One concise sentence that communicates the tool's purpose and return content, with a useful example. No redundant information.

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

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

For a simple one-parameter tool with full schema coverage, a clear output schema, and rich annotations, the description is sufficient for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with a detailed description and examples for the single parameter. The description merely repeats the example ('Naruto Uzumaki') and adds no new semantic meaning.

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

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

The description clearly states the verb+resource: 'Search for quotes by anime character name' and specifies the return fields (character, series, quote text), distinguishing it from siblings like search_by_anime and random_quote.

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 clearly establishes the context for using this tool (searching quotes by character), but does not explicitly mention alternatives or when not to use it. The sibling search_by_anime is not referenced, but the character-specific focus is 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?

Beyond the annotations, the description discloses return format (top-N passages with character offsets and similarity scores), algorithm (BGE-base-en + cosine over 500-char windows), and the 200K char truncation behavior. This is rich behavioral context with no contradiction.

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

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

Four sentences, each serving a distinct purpose: defining the operation, stating when to use, explaining pairing with a sibling, and describing technical mechanics. No fluff; well-organized.

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

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

No output schema exists, but the description covers return values (passages, offsets, similarity scores) and edge behavior (truncation flag). It is complete for a search tool with clear integration context.

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

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

Schema covers all parameters at 100%, so baseline is 3. The description adds value by clarifying text is 'already pulled' content, providing example queries, and referencing the 200K cap, enriching the schema descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which names a specific verb (search), resource (record/text), and scope (inside). It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and focusing on already-fetched text.

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: 'Use when the record is too big to cram into the prompt,' and provides a complementary workflow with ask_pipeworx_grounded. This gives clear context and names an alternative/companion tool.

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

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

The description goes beyond the annotations by disclosing important behavioral details: the need for an OAuth account, SMS verification and 10/day cap, and the fact that the feed is always on and retrievable via recent_alerts or a registry URL. This adds significant context about side effects, prerequisites, and constraints, and does not contradict 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 dense but well-structured, starting with the core action, then covering supported types in a clear list, followed by delivery channels. Every sentence carries essential information, and the organization makes it easy to scan for key facts like account requirements and channel constraints.

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 (multiple subscription types, nested delivery objects, no output schema), the description covers all essential context: what it does, return value, authentication prerequisites, supported types with examples, and delivery alternatives. It leaves no major gaps for the agent to interpret, especially with the additional details in the schema.

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

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

The schema already provides 100% coverage with detailed descriptions, including nested delivery options. The description adds semantic value beyond the schema, such as explaining that items:['5.02'] in sec_8k corresponds to an officer change and that fred_series monitors 'new FRED observations' with series_id example, which helps the agent understand the meaning of type-specific params.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream' and notes it returns the subscription id. It differentiates from sibling tools like list_subscriptions and unsubscribe by explicitly focusing on the creation action and enumerating supported subscription types.

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

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

The description provides clear context for when to use the tool, including account requirements (OAuth, anonymous/BYO cannot persist) and delivery channel specifics (feed always on, optional email/SMS with verification). It does not explicitly mention when not to use it or name direct alternatives, but it does reference recent_alerts for pulling feed data, which offers a complementary path.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context: that it returns example questions mapped to tools and argument shapes, and that it works without arguments or can be focused via topic. This supplements 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 dense but packed with useful details: the questions it answers, output format, parameter usage, and placement in the workflow. It is a single paragraph but each clause contributes, though it could benefit from slight restructuring for readability.

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

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

Given there is no output schema, the description compensates by explicitly explaining the return content (category-bucketed example questions with tool + argument shape). It covers both calling modes, mentions related meta-tools, and fits naturally amid a large sibling set by positioning itself as the first stop.

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

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

The schema already provides 100% coverage with a detailed description of the optional topic parameter, including valid focus areas and behavior for omission. The description repeats some examples ('finance', 'pharma', 'betting') but adds no new semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool returns category-bucketed example questions with the exact tool and argument shape, acting as an onboarding entry point. This is a specific, well-defined purpose that distinguishes it from sibling tools like discover_tools or ask_pipeworx.

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

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

Explicitly instructs to 'Use this FIRST' when the agent doesn't know what Pipeworx can do, and provides concrete example topics and the no-argument call pattern. This gives clear when-to-use guidance with no ambiguity.

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

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

Beyond the annotations (readOnlyHint: false, destructiveHint: false, idempotentHint: true), the description discloses critical behavioral details: ownership enforcement, deactivation (not deletion), and the impact on historical events via recent_alerts. This adds valuable context and fully aligns with the annotation hints.

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

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

The description is three sentences: the first states the action, the second imposes an ownership constraint, and the third explains the non-destructive side effect. Every sentence provides distinct information, with the purpose front-loaded. 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 single-parameter tool, the description combined with the schema and annotations is fully sufficient. It explains what happens to the row, who can call it, and the relationship to recent_alerts. The lack of an output schema is acceptable here, as the return value is not essential to understanding the tool.

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

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

The schema already fully describes the single parameter 'id' as a uuid returned by subscribe, achieving 100% coverage. The description only echoes 'by id' without adding extra syntax, format, or examples, so it does not meaningfully augment the schema information. 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 opens with an explicit action (Cancel) and resource (subscription) plus the key identifier (id), making the tool's purpose unmistakable. It distinguishes itself from siblings like subscribe and list_subscriptions by using 'cancel' while also adding a scope constraint (only your own), which clarifies its role.

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

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

The description clearly indicates when to use the tool (when you want to cancel a subscription) and adds a usage restriction (ownership enforced). It provides context by tying canceling to deactivation and recent_alerts, but it does not explicitly name alternatives (e.g., 'use subscribe to create' or 'use list_subscriptions to view'), so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description adds significant context beyond these: the crucial distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source covered), plus the presence of verification_error. It also discloses the return format with verdicts, evidence, and citations, giving thorough behavioral insight.

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 all details earn their place: trigger phrases, routing logic, return values, and the critical error-handling caveat. It is front-loaded with trigger phrases and organized with clear sections, though slightly verbose in listing all verdict types and the 'IMPORTANT for callers' note 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?

With no output schema, the description fully covers the return value (verdict types, actual value, citation, reasoning) and error semantics. It also explains the two processing paths (SEC EDGAR + XBRL fast path versus grounded pipeline) and how the tool replaces multiple sequential calls, making it complete for a complex verification tool.

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

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

Schema description coverage is 100%, with the schema already documenting 'claim' with a concrete example and 'tolerance_pct' with its default behavior. The description itself does not discuss parameters directly, so it adds no semantic value beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with the verb phrase 'fact check / verify the claim' and explicitly names the resource: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools by specifying the claim-verification niche and noting it replaces 4–6 sequential calls, making its purpose unmistakable.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing direct use-case guidance. It also explains how company-financial claims route to SEC EDGAR and all other claims fall through to the grounded pipeline, but does not explicitly name sibling tools or state when not to use this tool, so it stops short of a 5.

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