chucknorris

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable context beyond this: default model (Workers AI Llama-3.3-70b free), BYO Anthropic key with direct payment, and the per-model return structure. This gives practical operational details 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, with the main purpose front-loaded in the first sentence. The second sentence handles configuration, and the third sentence covers output and use cases. No wasted words; every sentence earns its place.

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

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

For a tool with 4 parameters, full schema coverage, and no output schema, the description is quite complete. It explains purpose, configuration, return format (per-model fields plus combined view), and use cases. A minor gap is not defining what 'signals' or 'confidence' mean, but this is likely acceptable for the target use case.

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 each parameter is already well-documented. The description restates the default model and _apiKey requirement but doesn't add new meaning beyond the schema. Given the high coverage, a baseline of 3 is appropriate; the default-model note is minor added semantics.

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

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

The description states a specific main action ('Probe one or more LLMs for what they know...') with a clear resource (business/brand/product/topic) and a concrete output (score 0-100 per model). It distinguishes itself from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on LLM knowledge and visibility scoring rather than general Q&A or competitor scanning.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the configuration option for adding Anthropic via _apiKey. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds valuable behavior: it fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is described as 'one fast call' that works on every tier. 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 front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and structured with clear guidance. Some lists (sources, examples) are repetitive, but for a default entry-point tool, the thoroughness is justified and each section earns its place.

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 comprehensively covers purpose, scope, usage triggers, alternatives, and return behavior (structured answer with citations). It also notes it works on every tier and is the default entry point, making it complete for such a broad routing 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 fully documents all six parameters as aliases for the single 'question' field, with descriptions. The description does not add parameter-specific format details beyond the schema, but schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It lists specific domains (SEC, FDA, FRED, etc.) and distinguishes itself 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?

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and gives conditional alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions. It also provides trigger phrases and concrete examples of when to use.

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

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

The description goes beyond the readOnly/idempotent hints by disclosing that routing improvements are "enabled live whenever one is under test," that no candidate is active right now, and that it currently matches ask_pipeworx exactly. It preempts assumptions by stating "Falls back to nothing — this IS a full working router," providing valuable behavioral context about the beta nature and dynamic equivalence.

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 packs essential information into four sentences, front-loading the beta version and equivalency statement. It is slightly dense but every sentence adds value; a small trim could improve readability, but overall it is concise and well-structured.

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

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

Given the tool's complexity and lack of output schema, the description fully covers its purpose, relationship to ask_pipeworx, current status (no active candidate), usage instruction, and experimental role. It is complete enough for an agent to decide when 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?

The input schema covers all six parameters with 100% description coverage, documenting the six aliases for `question`. The description adds no parameter-specific meaning, which is acceptable since the schema handles semantics thoroughly. Thus, the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as a "beta version of ask_pipeworx" with the same universal router functionality, listing the exact scope (5,529 tools, same arguments, same response shape). It differentiates from the stable sibling by framing it as "the experimental edge" and explicitly states it "is a full working router," leaving no ambiguity about its purpose.

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

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

The description provides explicit guidance: "Use it exactly like ask_pipeworx when you want the newest routing." It also explains the comparison against the stable router and notes that no candidate is active, meaning it currently matches ask_pipeworx exactly. While it implies this is for experimental usage, it does not explicitly recommend alternatives for stable needs, but the context is clear enough.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral traits: it returns a structured object with evidence, confidence, source, and a refusal_reason field, and it explicitly enumerates possible refusal reasons and scenarios. It also explains the underlying mechanism of using only tool result content, which is exactly the kind of context that helps an agent understand edge cases 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 dense but every sentence contributes essential information: the purpose, the behavioral guarantee, the return schema, refusal reasons, usage guidance, and cost trade-off. It is slightly longer than strictly necessary, but it avoids fluff and is well-organized with the core purpose front-loaded. A 4 reflects the appropriate balance between completeness and efficiency.

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 fully explains the return value structure, including both success and refusal cases, and lists all possible refusal_reason values. It also covers the cost implication and concrete high-stakes use cases, making the tool's behavior predictable and complete for an agent that needs 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 has 100% coverage: the single meaningful parameter 'question' is fully described, including all six aliases. The description adds no additional parameter semantics beyond what the schema already states, so the baseline score of 3 is appropriate for a schema that fully documents the parameters.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, specifying the exact workflow: routing, filling arguments, fetching data, and extracting answers only from the result. It explicitly distinguishes it from its sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior, leaving no ambiguity about its unique function.

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', listing concrete domains like financial verdicts, legal claims, and medical lookups. It also states when NOT to use it ('prefer ask_pipeworx for casual lookups') and mentions the cost trade-off (one extra LLM call), making the decision boundary crystal clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context beyond this: low-confidence matches short-circuit with status, closed/inactive markets skip fan-out, wide-spread markets carry tradeability warnings, resolution-rule risk is parsed into cancellation_rule, and GDELT rate-limit fallback behavior is disclosed via _fallback_attempted fields. No contradiction with annotations.

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

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

The description is long but deliberately structured and front-loaded: it starts with the core purpose and usage, then flags key system behaviors. Labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY) make it scannable. Every sentence carries operational detail; there is 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?

Since there is no output schema, the description takes full responsibility for explaining return values. It comprehensively covers response shapes (market, analysis, evidence), resolver contract fields, parent_event extractor, news fallback fields, status codes, and edge cases. It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains accepted input formats for 'market' (slug, URL, or question text), clarifies depth options ('quick = 2-3 evidence sources, thorough = full fan-out'), and details include_raw size implications (~20KB vs 50KB-500KB) with use cases. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the tool's function—resolving a market, classifying the bet, fanning out to data sources, and returning an evidence packet with a market-vs-model comparison. This distinguishes it from siblings like polymarket_arbitrage 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?

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete fan-out examples across varied bet types (BTC, Fed, Hormuz, Yankees, hottest-year, NVDA-vs-AAPL), giving clear situational guidance without needing to mention all alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it executes in one parallel call, sorts results by the primary metric, returns paired data with citation URIs, and correctly handles off-calendar fiscal years (e.g., AAPL, NVDA). This goes well beyond the annotations without contradicting them.

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

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

The description is appropriately sized for the tool's complexity and is well-structured: it starts with usage examples, then states the core capability, then per-type details, then output and efficiency benefits. Every sentence contributes useful information 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 only 2 parameters and no output schema, the description covers input semantics, output format (paired data + citation URIs), sorting behavior, and special-case handling (off-calendar fiscal years). It also conveys the tool's efficiency advantage, making it fully self-contained for an agent to decide when 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 goes further by explaining the meaning of each type value ('company' pulls 10-K revenue/net income/cash/debt; 'drug' pulls FAERS/FDA/trial counts) and provides concrete example arrays. This adds semantic depth that the schema alone does not convey.

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

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

The description clearly defines the tool as a side-by-side comparison of 2–5 companies or drugs in a single parallel call. It lists multiple natural-language triggers ("X vs Y", "which is bigger", "rank these companies") and explicitly differentiates it from sequential single-pack lookups, leaving no ambiguity about its purpose.

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

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

The description provides explicit usage guidance: "ALWAYS PREFER over sequential single-pack lookups when comparing entities." It also clarifies when each type (company vs drug) is appropriate and what metrics are pulled. However, it does not explicitly mention when to choose an alternative like entity_profile or deep_research, so it falls slightly short of fully covering when-not-to-use scenarios.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses account/plan requirements, findings packet structure (evidence + confidence + source + fetched_at + citation), gaps[] and contradictions[], citation_uri fetchability, semantic excerpting, second-hop iteration behavior, and latency expectations. Annotations are not contradicted; the description adds substantial operational 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 long but every section carries essential info: account constraints, use-case guidance, output format, depth semantics, latency, and limitations. It is front-loaded with the most critical operational note (account required). While dense, the structure is logical and no sentence is 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?

Despite no output schema, the description thoroughly covers return payload, gaps behavior, citation guarantees, semantic excerpting, depth modes, latency, and when NOT to use. It provides enough context for an agent to invoke the tool correctly and interpret results, making it highly complete for its complexity.

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

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

Schema coverage is 100% with descriptions for both question and depth, so baseline is 3. The description adds value by explaining depth-specific behaviors beyond schema (paid requirement for 'thorough', gap recovery, contradiction scan) and clarifying question scope ('Broad/multi-part is fine'). It enriches the parameters but does not fully redefine them.

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+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It explicitly distinguishes from siblings by noting 'this is NOT open-web search' and contrasting with ask_pipeworx, making the tool's unique purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and direct alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead.' This is model 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 the operation safe (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds valuable behavioral context by stating it returns 'full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed,' which goes beyond mere safety to explain the operational result and efficiency.

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

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

The description is compact—three sentences—and front-loads the primary action ('Find tools'), followed by concrete usage domains and return-value details. Every clause earns its place by conveying either purpose, context, or behavior, 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?

While there is no output schema, the description compensates by explaining the return shape ('names, descriptions, and full input schemas') and the value proposition ('ready to call directly, no second schema lookup needed'). It also covers when to use the tool first. It omits the default limit (handled in schema) and ranking criteria, but these are minor for a discovery tool of this 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 description coverage is 100%, with all six parameters (query and its aliases q, task, search, description, plus limit) fully described in the input schema. The description only loosely references 'top-N' and 'describing the data or task,' which adds minimal meaning beyond what the schema already provides, 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 begins with 'Find tools by describing the data or task,' which clearly states the verb (find) and resource (tools). It then enumerates specific domains (SEC filings, FDA drugs, FRED, etc.), distinguishing it from sibling tools like search_jokes or suggest_questions, making the purpose unmistakable.

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

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

The description explicitly states '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 provides clear when-to-use context and implies a contrast with tools that return a single direct answer, effectively guiding tool selection.

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

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

The description goes well beyond the annotations by detailing the fan-out across SEC EDGAR, XBRL, USPTO, news, and GLEIF, including fallback behaviors (GDELT→GNews) and soft-fail on patents. It also specifies return data structure (cik, filings, fundamentals, patents, LEI) and the fact that it performs a parallel call, which is valuable behavioral context.

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

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

The description is long but dense and front-loaded with natural-language triggers. It efficiently packs multiple data source names and return fields into a structured list, and every sentence carries useful information, so the length is justified even if slightly verbose for a tool description.

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

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

Given no output schema, the description does an excellent job of enumerating what will be returned (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It also discloses limitations like patent API sunset and the unsupported name input, making the tool's behavior predictable for an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: it clarifies the exact formats for value (ticker or zero-padded CIK), gives examples (AAPL, 0000320193), and reinforces the unsupported name input with a pointer to resolve_entity. This is more than just repeating the schema.

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

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

The description states exactly what the tool does: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs like 'Tell me about,' 'research,' and 'brief me on,' and clearly distinguishes itself from chaining single-pack lookups and from resolve_entity by noting that names are not supported.

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

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

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear alternative for names: 'use resolve_entity first if you only have a name.' This tells the agent exactly when and when not to use the tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is covered. The description adds little behavioral context beyond what annotations provide, though it clarifies that it deletes stored memories and suggests use cases, but no extra behavior details are disclosed.

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

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

The description is two sentences, front-loaded with the core action, and every clause earns its place by adding usage context or tool relationships. 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 one-parameter tool with no output schema, the description fully covers purpose, usage timing, and relationships to related tools. The annotations provide the safety profile, so nothing critical is missing.

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

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

The input schema has 100% coverage for the single 'key' parameter, which is described as 'Memory key to delete'. The description repeats the word 'key' without adding additional semantic meaning beyond the schema.

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

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

The description clearly states the verb ('Delete') and resource ('a previously stored memory by key'), making the tool's function unambiguous. It also distinguishes itself from siblings by mentioning pairing with remember and recall, clarifying its role in the memory lifecycle.

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 scenarios: stale context, task completion, or clearing sensitive data. It does not mention when not to use it or explicitly contrast with alternatives, but the mention of pairing with remember and recall gives context.

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

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

Annotations declare read-only, idempotent, and non-destructive behavior. The description adds context beyond annotations by explaining the process (fetches page, extracts title/description/key links) and the output format (standard llms.txt markdown). This enriches the agent's understanding without contradicting 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 serving a distinct purpose: what it does, how it works, and when to use it. No fluff, well-structured, and information-dense.

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

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

Despite no output schema, the description explicitly states the output is a single text blob ready for site-root/llms.txt, covering return value. Combined with annotations and use cases, the description is complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, with both url and max_links having descriptions. The description does not add significant semantic meaning beyond the schema; it just reiterates 'any URL' and implies link extraction. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a URL, with a specific verb (generate), resource (llms.txt), and scope (any URL). It distinguishes from siblings by focusing on the output artifact and includes the fetch/extract/emit process.

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

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

The 'Useful for' list gives three specific use cases, indicating when to use the tool. It does not explicitly name alternative tools or exclusions, but the context is clear enough for an agent to select it for llms.txt generation tasks.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which convey safety and non-mutating behavior. The description adds a small behavioral detail by stating the return includes joke text and ID. No contradictions with annotations, but it does not disclose error handling or other runtime behaviors beyond what annotations cover.

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

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

The description is a single, concise sentence that front-loads the core purpose and return value. No wasted words, and it fits the simple nature of the tool.

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

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

Given the tool has only one parameter, 100% schema coverage, an output schema, and comprehensive annotations, the description fully covers the essential information. It states what the tool does and what it returns. Nothing critical is missing 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 the parameter 'category' fully described as 'Category to fetch a joke from. Use list_categories to see valid values.' The description adds no extra parameter semantics beyond confirming it is a specific category, so the schema carries the burden adequately. Baseline 3 is appropriate.

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

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

The description clearly states the tool gets a random Chuck Norris joke from a specific category and returns the joke text and ID. The verb ('Get'), resource ('random Chuck Norris joke'), and scope ('from a specific category') are all explicit, distinguishing it from sibling tools like random_joke or search_jokes.

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

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

The description implies when to use this tool (when a joke from a specific category is needed) and the schema parameter description explicitly instructs to use list_categories for valid values. However, it does not mention alternatives like random_joke for unfiltered jokes or search_jokes for searching, so it lacks explicit exclusions or named alternatives.

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

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

The description claims to list 'all available' categories, but the annotations set openWorldHint=true, meaning the tool's output may not be exhaustive. This directly contradicts the annotation, so transparency is severely lacking.

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, immediately states the purpose, and then a useful usage hint. No wasted words.

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

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

The tool is simple with no parameters and an output schema, but the description's 'all available' claim is inaccurate given openWorldHint, creating a meaningful gap in completeness. It should have hedged or explained that results may not be exhaustive.

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?

There are zero parameters, so the description needs no parameter-level detail. Baseline for 0 params is 4, and the description does not need to add anything else.

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 the specific verb 'List' with the resource 'all available Chuck Norris joke categories' and gives concrete examples ('nerdy', 'sport'). It clearly distinguishes this from sibling tools like random_joke or search_jokes.

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

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

It explicitly says 'Use with joke_by_category to fetch jokes', which provides clear context for when to use this tool. However, it does not mention when not to use it or alternatives beyond joke_by_category.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, establishing the safe read-only nature. The description adds value by specifying the scope ('caller's active subscriptions') and the exact return fields (id, type, params, created_at, last_fired_at, fire_count), which are not in the annotations. No contradictions.

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

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

The description is two sentences long, with the first sentence stating the purpose and return fields, and the second providing usage guidance. Every word earns its place—no fluff or repetition.

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

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

For a simple, read-only list tool with a single optional parameter and no output schema, the description covers purpose, return fields, and usage context. The include_inactive parameter is documented in the schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, and the only parameter (include_inactive) already has a clear description in the schema. The tool description does not add any parameter-specific meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' This uses a specific verb ('list') and resource ('subscriptions'), and distinguishes it from sibling tools like subscribe and unsubscribe. It also lists the return fields, further clarifying 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 explicitly tells when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implies alternatives (subscribe to add, unsubscribe to cancel) without needing to name them explicitly.

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 (which are all false) by disclosing rate limits ('Rate-limited to 5 per identifier per day'), the claim_token follow-up mechanism ('Filing without an account returns a claim_token; pass it back later'), and the team's response cadence ('reads digests daily'). It also instructs on appropriate content ('don't paste the end-user's prompt'), which shapes the tool's side-effect profile.

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

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

The description is a single dense paragraph that front-loads the core purpose in the first sentence, then branches into use cases, exclusions, claim_token, and rate limits. Every sentence carries information, but the length is somewhat high; it could be tightened into a bulleted structure, so it earns a 4 rather than a 5.

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 lack of an output schema, the description fills the gap by explaining exactly what the tool returns: a claim_token for anonymous submissions and a status/change report when passing that token back. It also covers operational details like rate limiting and quota impact. The tool is a feedback submission channel, and the description covers all necessary context for an agent 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?

Although the input schema describes all 4 parameters (100% coverage), the description adds meaningful usage guidance: it explains how the claim_token parameter works as a follow-up handle and advises how to structure the message ('Describe the issue in terms of Pipeworx tools/packs'). It also clarifies that claim_token is used 'with no other arguments,' which is not in the schema.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource: submitting feedback about Pipeworx tools. It enumerates feedback types (bug, feature, data_gap, praise) and explicitly differentiates from sibling MCP tools by limiting scope to 'tools served by this Pipeworx connection.'

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 a when-not-to-use and an alternative: 'if the tool came from a different MCP server... file it with that server instead.'

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, safe. The description goes further by explaining the data source (CF analytics-engine), absence of PII, output shape (pack, tool, count), and caching policy (5min-1h), which adds valuable operational 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?

The description opens with a clear hook, then lists outputs, use cases, and data characteristics. Each sentence carries distinct information; the use-case bullets are efficient and the provenance/caching details are valuable. No filler.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers all necessary context: what is returned, available windows, purpose, data source, privacy, and caching. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The single 'window' parameter is fully documented in the schema with enum and semantic explanation of shorter vs longer windows. The description repeats the options but adds no new parameter semantics beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description clearly states the tool returns trending data about other AI agents' usage: top tools, top packs, and call volume over a window. The specific outputs and timeframe distinguish it from sibling tools like discover_tools or recent_alerts.

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

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

The 'Useful for' list gives three concrete scenarios (discovering hot sources, confirming canonical tool, aligning use case). However, it does not explicitly contrast with alternatives or state when not to use, so while context is clear, exclusions are absent.

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

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

The description goes far beyond the read-only/idempotent annotations by disclosing internal logic: Jaccard similarity threshold, partition placeholder fraction limit, >3pp deviation for BUY/SELL signals, and the fill check behavior with 'realizable_edge_pp ≤ 0' meaning 'do not trade it'. These are valuable, non-obvious behavioral details.

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

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

The description is long but well-structured using section-like breaks (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It front-loads the core purpose and then methodically covers modes, response format, and caveats. Every sentence carries functional information; no filler text.

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

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

Given the tool's complexity (multiple modes, thresholds, edge cases) and the absence of an output schema, the description compensates by fully specifying the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers failure/edge cases like placeholder slugs and thin books, making it highly complete.

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

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

Schema descriptions already provide solid coverage of both parameters with examples. The description adds extra clarity by explaining how each parameter drives the analysis: event slugs 'walk child markets' and compute partition_check, while topic seeds are expanded to 'search related events... flattens markets, runs the comparator on the union.' This goes beyond the schema's literal field definitions.

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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly identifies the tool's unique approach and distinguishes it from siblings like polymarket_edges and polymarket_fill_risk. The two modes (event, topic) are explicitly explained, reinforcing purpose clarity.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This makes when-to-use and when-not-to-use very clear.

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

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

The description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), response diagnostics, and a warning when a 24h market move exceeds the edge. It also explains why Fed bets are excluded and details gate relaxation logic. These go well beyond the read-only/idempotent annotations.

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

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

The description is a single, very dense paragraph exceeding 300 words. It includes internal model details like specific alpha values (tennis 1.02) and gate relaxation thresholds that are not necessary for tool invocation. While front-loaded with purpose, the sheer volume and lack of structured formatting hurt readability 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?

With no output schema, the description thoroughly explains the response top-level structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, etc.). It also covers knobs, caching, and warnings, ensuring the agent knows exactly what to expect. Highly complete 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?

Even with 100% schema description coverage, the tool description adds crucial cross-parameter semantics. It explains why min_kelly never filters partition arbs (parent kelly_fraction_half=0 by design) and that min_partition_leg_kelly applies per-leg instead. This clarifies behavior not evident from individual parameter descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings by focusing on 'what should I bet on today' and avoiding manual scanning. The verb 'scan' and resource 'Polymarket markets' are 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?

It gives clear usage context: designed for opportunity discovery without paging hundreds of markets. It explains how to adjust tradeable-edge knobs (min_liquidity, max_spread_pp) and notes Fed bets are excluded from ranking due to signal unreliability. However, it does not explicitly contrast with alternatives like polymarket_arbitrage or polymarket_edge_tracker.

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, non-destructive behavior. The description goes far beyond by disclosing response structure (tracked/expired/snapshot_dates), data-gap causes (cache-miss), TTL limits (60-day snapshot TTL), and that decay is computed on daily closes, not intraday. This provides rich behavioral context without contradicting annotations.

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

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

The description is front-loaded with the core purpose, then systematically covers args, response format, and limitations. Every sentence provides essential detail (e.g., the meaning of expired[] and the median lifespan clock), earning its place. The structure with sections (Args, RESPONSE, LIMITS) aids 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?

With no output schema, the description fully explains the return format, including field meanings and edge cases like snapshot gaps and TTL bounds. It also covers limitations about history depth and data calculation, making the tool self-contained for an agent to use correctly.

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

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

Schema coverage is 100% with clear parameter descriptions for days and window. The description restates these defaults and adds minimal context (e.g., 'lookback', 'snapshot family'), but does not significantly enhance 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 explicitly states it provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. This clearly identifies the tool's function and differentiates it from siblings like polymarket_edges, which focus on 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 gives a clear use case: comparing fresh vs. old wide edges, implying when to use this tool. However, it does not explicitly name alternatives or state when NOT to use it, but the context makes the distinction clear enough.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. Description adds significant context: walks the order-book ladder, returns a verdict, exposes thin_legs and forced_directional_risk, and warns that partial basket fills create unhedged directional positions — the dominant loss mode. 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?

Long but every sentence earns its place. Structured with SINGLE-MARKET and BASKET sections, front-loaded with the core purpose, and includes output lists and risk rationale without redundancy. Appropriate 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?

Despite no output schema, the description enumerates all key return fields in both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers prerequisites, parameter semantics, and behavioral rationale, making it fully self-contained for a complex tool.

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

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

Schema coverage is 100%, but description adds strong extra semantics: explains that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional — shares per leg' in basket mode; clarifies mode selection via market vs event; documents side defaults and auto-detection. This goes far 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?

States 'Realizable-vs-theoretical edge check against live CLOB order-book depth' — a specific verb+resource. The explicit 'USE THIS before acting on any polymarket_arbitrage... or polymarket_edges trade above ~$500' clearly differentiates it from sibling arbitrage/edge 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 explicit when-to-use guidance: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Names alternative tools and rationale for the threshold, making usage conditions unambiguous.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive behavior. The description adds extensive context beyond annotations: compatibility_warning with two distinct cases, temporal_alignment, skipped_cross_type/subtype counters, and the caveat 'pre-mapped ≠ tradeable.' 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 clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries critical information, though it could be slightly tightened without losing key caveats. The density is justified by 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?

For a complex cross-venue comparison tool with no output schema, the description thoroughly covers inputs, modes, output semantics, and reliability conditions. It even explains why spreads may be meaningless (compatibility_warning, temporal_alignment), making the tool usable in real-world scenarios.

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 enriches each parameter: it lists the full topic enum, gives concrete examples for ticker/slug ('KXFED-26OCT', 'fed-decision-in-june-825'), and explains override semantics. It also explains response fields like top_spreads_pp and compatibility_warning, adding meaning beyond the schema.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by explicitly naming both venues and the comparison nature.

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

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

The description provides explicit usage context by detailing TWO MODES (topic shortcuts vs explicit pairing) and warns that pre-mapped topics may not be tradeable. It does not explicitly name alternative tools or exclusionary conditions, but the compatibility_warning and temporal_alignment fields serve as clear when-not-to-use signals.

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

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

Annotations already cover read-only and idempotent behavior. The description adds useful context by naming the external API (chucknorris.io), implying potential network dependency, and listing the exact return fields, which goes beyond the safe-read annotation.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds value. It states the source, the action, and the return payload without superfluous words.

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

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

For a zero-parameter tool with an output schema, the description adequately covers the purpose and return values. It mentions all key output fields (joke text, ID, category list, permalink) and gives the external source, making the tool behaviorally complete for an agent.

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

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

The tool has zero parameters, so the description does not need to explain parameter behavior. The baseline for zero-parameter tools is 4, and the description does not introduce any irrelevant parameter details.

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 action ('Fetch one random Chuck Norris joke') and identifies the external source (chucknorris.io). This distinguishes it from sibling tools like joke_by_category and search_jokes, which have different purposes.

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

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

The description implies usage for obtaining a random joke, and the sibling list gives context for alternatives, but it does not explicitly state when to use this tool over others or mention exclusions. Still, the context is clear enough for a user to infer the appropriate use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond those annotations: the tool is scoped to an identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys. This enriches the agent's understanding of isolation and 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?

Three sentences, front-loaded with the primary action, followed by a practical usage note and scoping detail. Every sentence contributes new information and there is no fluff.

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

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

This is a simple tool with one optional parameter and no output schema. The description covers the key behaviors (retrieve by key, list all, scope) and pairs it with related tools. Given the low complexity, the description is fully sufficient for an agent to decide and invoke it correctly.

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

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

The schema already describes the only parameter ('Memory key to retrieve (omit to list all keys)') with 100% coverage. The description reinforces this by explaining the omit-to-list behavior and giving example keys, but it does not provide new syntactic or format details beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes itself from sibling tools remember and forget, and provides concrete use-cases like 'user's target ticker, an address, prior research notes.'

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 on when to use the tool: 'Use to look up context the agent stored earlier — without re-deriving it from scratch.' It also names companion tools ('Pair with remember to save, forget to delete'), but does not explicitly state conditions for when not to use or contrast with alternatives like deep_research or search_within, so it falls short of a 5.

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

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

Beyond the annotations, the description discloses that mark_read:true flags events as read so subsequent calls return only newer events—a side effect not implied by readOnlyHint. It also explains the citation_uri format and raw payload structure, providing rich behavioral context.

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

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

Two sentences, front-loaded with the core action, and every clause contributes: return fields, filters, mark_read behavior, polling suitability, and alternative URL. 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?

For a 5-param tool with no output schema, the description covers the return format, filtering options, mark_read side effects, and alternate access. It also implicitly addresses unread_only and limit via the schema while providing enough context for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds an example type ('sec_8k') and clarifies the behavioral consequence of mark_read, which exceeds the schema descriptions. This meaningful addition justifies a 4.

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

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

The description opens with 'Pull fired events from your subscription feed,' naming the specific verb and resource. It clarifies the return payload (source, citation_uri, raw event payload) and distinguishes itself from sibling tools like list_subscriptions by focusing on alerts from the persisted 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?

It states 'Polls work fine' and offers an alternative access method via URL for scripts/dashboards, providing context on when to use this tool directly vs. programmatically. However, it does not explicitly position itself against sibling tools or give when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, but the description adds substantial context: the parallel fan-out to multiple sources, GDELT→GNews fallback logic, USPTO soft-fail due to API sunset, accepted date formats, and the output structure (changes[], total_changes, citation URIs). This goes well beyond the annotations.

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

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

Despite its length, every clause serves a purpose: examples front-loaded for quick recognition, then core functionality, fallback details, parameter formats, return structure, and an explicit alternative. It is dense but well-organized, with no filler.

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

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

Given the complexity (multi-source, fallback, date parsing) and absence of an output schema, the description covers all essential aspects: what sources are queried, behavior on failures, expected output shape, and parameter syntax. It fully equips an agent to select and invoke the tool correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. The description enriches it further by providing examples for `since` ('7d', '30d', '3m', '1y', ISO dates), explaining `value` as ticker or zero-padded CIK with examples, and clarifying that `type` currently only supports 'company'. This adds practical meaning beyond the schema.

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

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

The description clearly defines the tool as a 'change feed for a company' and includes concrete query examples ('What's new with X', 'latest on Y'), differentiating it from the sibling entity_profile. It specifies the exact resources (SEC filings, news mentions, patents) and the window parameter, 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?

It explicitly states when to use this tool (for time-bounded change tracking) and provides a direct alternative: 'Use entity_profile instead when you want the static profile...'. This gives the agent clear decision criteria and avoids ambiguity with siblings.

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

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

Beyond annotations (readOnly=false, idempotent=true, destructive=false), the description adds key behavioral context: memory is scoped by the agent identifier, persistent for authenticated users, and retained 24 hours for anonymous sessions. This clarifies lifespan and scoping without contradicting the annotations. No mention of overwrite behavior, but idempotent hint covers this adequately.

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 with no wasted words. It front-loads the purpose, then adds usage guidance, persistence details, and sibling relationships. Every sentence earns its place and the structure is logical.

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 2-parameter tool with no output schema, the description covers purpose, usage triggers, persistence semantics, and complementary tools. It explains enough for the agent to invoke correctly without needing to understand return values. The annotations and schema fill in the remaining safety and parameter details, making the description complete in 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% as both parameters have descriptions. The tool description reinforces the 'key-value pair' concept and gives examples, but these examples are already present in the schema descriptions (e.g., 'findings, addresses, preferences, notes'). Thus the description adds minimal new semantic meaning beyond the schema, aligning with the baseline of 3.

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

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

The description opens with a clear verb+resource: 'Save data the agent will need to reuse later' and specifies it works across conversations/sessions. It distinguishes from siblings by explicitly naming recall and forget as complements, making the tool's role in the memory trio 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 usage guidance: 'Use when you discover something worth carrying forward' with concrete examples like ticker, address, preference, research subject. It also tells the agent to pair with recall for retrieval and forget for deletion, effectively outlining when to use this tool versus its siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral context: identifiers are labeled with sources, unresolved identifiers are explicitly stated, and GLEIF/OpenFIGI enrichment degrades gracefully if unavailable. It also mentions internal cascading through multiple endpoints, which is 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 front-loaded with concrete examples, followed by a clear purpose statement and structured supported-type details. Every sentence contributes useful information (sources, degradation behavior, output labeling). While longer than average, the length is justified by the tool's complexity and the absence of an output schema.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly explains return values (identifiers labeled with sources, unresolved stated explicitly), input types, and fallback behavior. It covers cross-source resolution, graceful degradation, and the internal replacement of manual lookups, making it fully self-contained for an agent.

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

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

Schema description coverage is 100%, so both parameters are fully documented. The description largely repeats the schema's parameter documentation (e.g., for value: 'ticker (AAPL), CIK (0000320193), or name' and 'brand or generic name'). It adds minor contextual examples but does not significantly extend beyond the schema, matching the baseline of 3.

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

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

The description clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It uses a specific verb (resolve) and resource (names to IDs), and the supported types (company, drug) with detailed identifier sources distinguish 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 explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also notes that 'using resolve_entity replaces 2-3 manual lookups,' implying efficiency. However, it does not explicitly mention alternatives or when-not-to-use scenarios, though the context strongly implies the guideline.

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 behavioral context beyond annotations: it discloses that the tool internally probes with ai_visibility_check, ranks by score, and returns ranked results with score, confidence, and signal density. This complements the readOnly/openWorld/idempotent annotations by describing the composite, rank-producing behavior. It could be more expansive about error handling or rate limits, but the provided detail is strong.

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 with no wasted words. It front-loads the purpose, then explains the mechanism, usefulness, and return value. The example quote is succinct and memorable. Every sentence earns its place.

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 moderate complexity (4 params, composite operation, no output schema), the description covers the key points: what it compares, how it works, use case, and return format. It could mention potential limitations (e.g., number of entities, model behavior), but the schema already handles entity bounds, and annotations cover safety, making the description reasonably complete.

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

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

Schema coverage is 100%, with each parameter already described clearly. The description adds semantic value by noting that the first entity is treated as the 'subject' for narrative, and the rest are competitors, which is not fully evident from the schema alone. It also ties models and _apiKey together implicitly, reinforcing their relationship.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), resource (AI visibility), and scope (multiple entities), and distinguishes from sibling tools like ai_visibility_check by focusing on multi-entity comparison. The example 'does Claude know about us as well as our competitors?' encapsulates the intent.

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 ('Useful for competitive AI-marketing audits') and implies the alternative: since it probes each entity with ai_visibility_check, a user needing a single entity check should use that sibling tool instead. However, it does not explicitly state 'use this instead of X' or list exclusions, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral nuances: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s and may appear in sources_failed on timeout, and the return format includes summary block, per-advisory detail, links, and alternatives. This adds significant context beyond what annotations alone provide.

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

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

The description is dense but every sentence contributes value: purpose, usage triggers, return contents, ecosystem limitations, and failure behavior. It is structured with a clear flow and avoids fluff, making it 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?

Given the tool's composite nature and no output schema, the description thoroughly covers inputs, outputs, edge cases (timeout, partial failures), and ecosystem constraints. It includes a detailed list of returned fields and error behavior, making it complete for an agent to invoke successfully.

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 fully documents both parameters (package and version) with descriptions, achieving 100% coverage. The description adds no parameter-specific detail beyond what the schema provides, so the baseline of 3 is appropriate. It mentions output fields like is_latest but that relates to return values, not parameter semantics.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package to my project' check, specifying it fans out to deps.dev and bundlephobia. The verb 'scan' combined with 'dependency' is concrete and distinguishes it from the listed siblings, which cover different domains like jokes, research, or entity profiles.

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

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

Explicit guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides an exclusion for non-npm ecosystems ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), which is crucial for tool selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing it as a safe read-only operation. The description adds the behavioral detail that it returns matching jokes with text and IDs, but this is modest and largely intrinsic to a search function.

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

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

The description is two sentences with no filler. It front-loads the action and directly states the return content.

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 a single parameter with full schema coverage, output schema, and comprehensive annotations. The description adequately conveys the tool's purpose and behavior for its simple scope; it doesn't mention pagination or search constraints, but these may be covered by the output schema.

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

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

The input schema has 100% description coverage, with the query parameter clearly defined as 'Keyword or phrase to search for within joke text.' The description's mention of 'keyword' adds no additional 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 uses a specific verb ('Search') and identifies the resource ('Chuck Norris jokes'), and clarifies the return format ('matching jokes with text and IDs'). This clearly distinguishes it from sibling tools like random_joke or joke_by_category.

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 the tool is for keyword-based search, providing clear context. However, it does not explicitly compare itself to sibling tools or state when not to use it, such as for random jokes or category filtering.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds substantial behavioral detail: top-N passages with character offsets and similarity scores, BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and a 200K char cap with truncation flag. This goes well beyond what annotations provide.

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

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

Three sentences, perfectly front-loaded with the core purpose. Each sentence adds value: use case, output details, pairing, and technical implementation. No fluff 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 tool with 3 params and no output schema, the description covers inputs, outputs (passages with offsets/scores), use case, limitations (truncation), and integration with the gateway. Everything an agent needs to invoke correctly is present.

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

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

Schema covers 100% of params, so baseline is 3. Description adds real-world usage context for text ("a SEC 10-K body, an article, a long tool result") and query examples, plus mentions limit defaults. This adds meaningful semantic color beyond the schema, warranting 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?

Purpose is crystal clear: "Semantic search INSIDE a fetched record" with concrete examples (SEC filing, article, long tool result). It distinguishes from siblings by explicitly framing search as operating on already-fetched content and pairing with ask_pipeworx_grounded.

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

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

Explicit "Use when the record is too big to cram into the prompt" and a complementary alternative: "Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document." No explicit when-not, but clear context indicates when this tool is appropriate.

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

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

Beyond annotations, it adds critical behavioral context: auth requirements, SMS phone verification with a 10/day cap, and the always-on feed. It also notes that anonymous users cannot persist subscriptions. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, etc.).

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: starts with purpose, then requirements, supported types with examples, and delivery channels. Every sentence provides value, and the length is justified by the tool's complexity.

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

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

Given no output schema, the description covers the return value, auth prerequisites, all subscription types (though examples cover a subset), and delivery methods. It's complete enough for an agent to decide and invoke confidently, and sibling context (list_subscriptions, unsubscribe) isn't needed for understanding this creation flow.

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 the schema covers 100% of parameters, the description enriches the semantics with concrete examples (e.g., items:["5.02"] = officer change, params:{topic:"fed"}) and constraints (SMS verification, cap). It adds meaning beyond the schema's enum and object descriptions.

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

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

The description clearly states the verb 'Create' and the resource ('proactive monitoring subscription to a live-data event stream') and explicitly mentions the return value ('Returns the new subscription id'). It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation and listing 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?

It provides explicit prerequisites ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)') and suggests alternatives for retrieving alerts ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It also details delivery channel options, giving clear context on when to use each.

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

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

Annotations already declare read-only/idempotent, so the description doesn't need to re-state safety. It adds meaningful behavioral context by describing the output as 'category-bucketed example questions' with 'exact tool + argument shape', and explains how omitting vs passing topic changes the response ('full spread' vs focused). This goes beyond annotations.

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

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

The description is moderately long but front-loaded with example queries and a clear statement of purpose. Every sentence adds value (coverage of categories, tool-linkage, usage tips). It could be tightened slightly but remains effective and well-structured.

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

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

For a one-optional-param tool with no output schema, the description fully covers the return structure ('category-bucketed example questions' with tool+argument shapes), the behavioral difference based on topic, and the recommended usage scenario. It also hints at the broader tool ecosystem, making it complete for an onboarding entry point.

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

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

Schema coverage is 100%, so baseline is 3. The description adds behavioral meaning beyond the schema by explaining 'Call with no arguments for the full spread, or pass topic to focus', reinforcing the parameter's effect and providing examples like 'finance', 'pharma', 'betting' that clarify usage.

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

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

The description explicitly states the tool is 'the onboarding entry point' and returns 'category-bucketed example questions', with a clear verb 'suggest'. It distinguishes from siblings by saying 'Use this FIRST when you do not yet know what Pipeworx can do for you' and by naming meta-tools to learn to call.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing a clear when-to-use. It doesn't explicitly state when not to use, but the 'FIRST' implies it's not for when you already know. It also gives examples of topic values, adding practical context.

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

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

Annotations already set readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral details: ownership enforcement and soft-delete via deactivation, preserving historical events in recent_alerts. This goes well beyond what annotations convey.

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

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

The description is two sentences with the core action front-loaded ('Cancel a subscription by id'). The second sentence earns its place by explaining ownership and side-effect behavior, with no filler.

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

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

For a single-parameter mutation tool with no output schema, the description covers the action, precondition (ownership), and postcondition (deactivation with history preservation). It is complete enough for an agent to invoke correctly.

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

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

The input schema already documents the id parameter well, but the description adds the ownership constraint, clarifying that the id must belong to the caller. This is meaningful semantic enrichment beyond the schema's basic description.

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

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

The description opens with 'Cancel a subscription by id,' using a specific verb and resource. It clearly distinguishes from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action.

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: cancel a subscription by id, with ownership enforced. It doesn't explicitly mention alternatives, but there is no competing cancellation tool among the siblings, so the context is sufficient.

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

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

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: it explains the two execution paths, return values, verdict meanings, and especially the critical distinction between could_not_verify (a failure) and unsupported (no source). This goes well beyond what annotations alone convey.

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

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

The description is dense and front-loaded with trigger phrases, but it remains well-organized and each section serves a purpose (usage, pipelines, verdicts, warnings). It is longer than average but avoids redundancy and earns its length given the tool's complexity.

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

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

With no output schema, the description fully covers return values (verdict, actual value, citation, reasoning) and edge cases (could_not_verify with error object, unsupported). It also explains the tool's role relative to a multi-step pipeline, making it self-contained for an AI agent.

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

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

Schema coverage is 100% for both parameters, and the description further enriches them: it gives concrete example claims, explains how tolerance_pct overrides implied tolerance, and specifies the default behavior. This adds material guidance beyond the schema.

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

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

The description clearly defines the tool as a natural-language claim verification tool with a specific verb and resource ('fact check', 'verify the claim'). It distinguishes itself from siblings by returning a verdict (confirmed/refuted/etc.) and by handling company-financial claims via a structured EDGAR pipeline and all other claims via a grounded pipeline.

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 whenever the agent needs to check whether something a user said is factually correct.' It also provides clear guidance on claim types (company-financial vs. any other) and states that could_not_verify must not be treated as evidence. It does not explicitly name alternative tools to use instead, but the usage context is strong.

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