Htmltext

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

The description adds transparency beyond annotations by detailing the probe behavior, default model, and that Anthropic requires a BYO key with direct payment. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive; there is no contradiction.

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

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

The description is two sentences, front-loaded with the core purpose, and every clause adds necessary detail. No wasted words.

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

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

Given the absence of an output schema, the description specifies the return format per-model and combined view. The 4 parameters are fully documented with purpose and defaults, making the tool's usage clear.

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?

All 4 parameters are described in the schema (100% coverage). The description adds value by explaining the default model for 'models' and the purpose of '_apiKey' and 'context', which 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 uses specific verbs ('probe', 'score') and resources ('LLMs for ... business/brand/product/topic') and clearly states the output (visibility score 0-100). It distinguishes itself from siblings like ask_pipeworx by focusing on visibility scoring rather than general questions.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the _apiKey (for Anthropic). It does not explicitly mention when not to use this tool versus alternatives, 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, idempotent, etc.), the description discloses routing behavior, the scale of sources (5,501 tools), and the return format with stable pipeworx:// citation URIs. It also notes it's a single fast call and works on every tier, adding useful context not present in 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 (~200 words) but well-structured with a clear directive, examples, and step-up guidance. While slightly repetitive (e.g., 'PREFER OVER WEB SEARCH' and 'Use whenever... even if web search could also answer it'), every sentence serves a purpose and the key directive is front-loaded.

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

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

For a complex routing tool with no output schema, the description covers trigger phrases, domain coverage, return type (structured with citations), performance characteristics, and alternative tools. It provides enough context for an agent to select and invoke it appropriately, including examples and boundary conditions.

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 with six alias parameters and a clear description explaining that 'question' accepts natural language and aliases. The description adds no new parameter-specific semantics beyond the schema, but it does illustrate valid inputs through examples, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool answers factual questions by routing to 5,501 tools across 1441 sources and returning structured answers with citations. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, making the purpose distinct.

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

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

It gives explicit 'when to use' guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever the user asks...' plus trigger phrases and concrete examples. It also explains when to step up to ask_pipeworx_grounded or deep_research, offering clear 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, non-destructive), the description discloses that candidate routing improvements are enabled live when under test, and that currently no candidate is active so it matches ask_pipeworx exactly. This added context about the experimental and potentially varying behavior is valuable for an agent deciding whether to use this beta tool.

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

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

The description is three sentences, front-loaded with the beta status and identical nature, then explains current state, usage, and that it's a full working router. Every sentence earns its place, providing essential information without redundancy.

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

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

For a beta router with no output schema, the description covers the key contextual elements: identity, relationship to stable, current behavior, and that it is a functional router not a fallback. It references 'same response shape' but doesn't detail the response format, which is acceptable given the tool's nature and the presence of annotations.

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 'question' parameter fully described as natural language accepting aliases. The description does not add parameter semantics beyond the schema, which is acceptable given the high schema coverage. Baseline of 3 applies.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,501 tools, arguments, and response shape, but with candidate routing improvements under test. It distinguishes itself from ask_pipeworx and ask_pipeworx_grounded by explicitly framing it as the experimental edge.

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 it exactly like ask_pipeworx when you want the newest routing,' giving a clear when-to-use directive. It also explains that results are compared against the stable router to decide merges, providing context for when this experimental edge is appropriate. It doesn't spell out explicit exclusions, but the guidance 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?

The description discloses behaviors beyond the annotations: it uses ONLY what the tool result contains, returns explicit refusal reasons with enumerated values, and costs an extra LLM call. These are important behavioral traits that the annotations (readOnlyHint, idempotentHint) do not specify. There is no contradiction with the annotations.

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

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

The description is front-loaded with the core purpose ('Hallucination-resistant answer mode'), then logically details the mechanics, return format, refusal reasons, and usage trade-offs. Every sentence carries unique information, and the length is justified by the complexity of a tool that must clearly communicate its guardrails and refusal behavior.

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

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

The description is fully complete for this tool's complexity. It explains the routing algorithm, evidence extraction, return structure, refusal reasons, cost differential, and appropriate usage scenarios. Even without an output schema, the agent has enough detail to understand what to expect and when to invoke this tool.

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

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

Schema description coverage is 100%: all parameters are documented in the input schema, including aliases. The description adds no parameter-specific semantics beyond what the schema provides, but because the schema is complete, a baseline score of 3 is appropriate. The description does not need to compensate.

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 ('EXTRACTS') and resource ('answer mode for high-stakes reads'), and explicitly distinguishes itself from sibling ask_pipeworx by naming it and emphasizing the grounded, hallucination-resistant nature. It also clearly states the return value structure (answer, evidence, confidence, etc.) and refusal conditions, leaving no ambiguity about what the tool does.

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 whenever an answer will be quoted, cited, or acted on...' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' It also gives concrete examples of high-stakes domains (financial verdicts, legal claims, medical lookups, public statements) and notes the additional cost trade-off, which is exactly the kind of contextual guidance expected.

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 is exceptionally detailed about behavior: fan-out logic, resolver contract, edge warning, cancellation rule parsing, safety mechanisms (low-confidence match, closed markets), and response shape. Annotations (readOnlyHint, idempotentHint, etc.) are consistent and the description adds extensive context beyond them. 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 long but front-loaded with the most essential information (first sentence). It uses structured headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) for readability. While comprehensive, every sentence adds value for a complex tool. Could benefit from slight tightening, but overall well-structured.

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

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

Despite lacking an output schema, the description fully specifies the return structure (result.market, result.analysis, result.evidence, etc.) and covers edge cases (low-confidence, closed markets, wide spreads, resolver contract details). This provides complete guidance for agents to interpret results correctly.

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

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

The description adds significant meaning to all three parameters beyond the schema descriptions. For 'market', it explains three input formats (slug, URL, question) and uses examples. For 'depth', it clarifies quick vs thorough. For 'include_raw', it explains default behavior and payload size implications (20KB vs 50-500KB). Schema coverage is 100%, and the description compensates richly.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, or question) and provides typical use cases. However, it does not explicitly differentiate from sibling tools like 'polymarket_edges' or 'ask_pipeworx', though context implies a distinct comprehensive research 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 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 provides multiple examples. However, it does not give explicit when-not-to-use guidance or alternatives, though the context of sibling tools provides implicit differentiation.

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 details data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorted results, and citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with example queries and structured into clear sentences about data sources and behavior. It is slightly verbose but every sentence adds value.

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

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

Given no output schema, the description explains return format (paired data + citation URIs) and sorting. It covers key use cases and data sources. Could specify handling of missing entities, but acceptable.

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 value by giving concrete examples (tickers/CIKs for company, drug names) and explaining behavior based on type. It clarifies max/min items and use of primary metric sorting.

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 performs side-by-side comparison of 2-5 companies or drugs, with specific example queries. It distinguishes itself from siblings like entity_profile by focusing on multiple entities comparison.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong when-to-use guidance. It does not explicitly mention when not to use or alternatives, but the context is clear.

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

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

Beyond annotations, describes return format (findings packet with verbatim evidence+confidence+source+fetched_at+citation), explicit gaps[] never invented, contradiction scan, semantic excerpting, and latency expectations. Clarifies it is NOT open-web search, adding meaningful constraints beyond readOnly hints.

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

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

Long but dense; every clause adds a distinct behavioral constraint or usage boundary (account, open-world distinction, citation resolvability, latency). Front-loaded with account requirement and key sibling contrast. Slightly dense but 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?

Complete for a complex tool with no output schema: explains return values, error/empty behavior (gaps), latencies, and depth tradeoffs. Covers account requirements and when not to use it, so an agent can correctly select and 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 has 100% coverage for question and depth. Description enriches depth semantics with behavioral consequences (gap-recovery hop, lead chase, contradictions scan) and gives examples for question formulation. This adds context beyond schema, though schema itself is already descriptive.

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 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources' with a clear verb+resource. Explicitly distinguishes from sibling ask_pipeworx for single lookups, making its unique purpose obvious.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and named alternatives: 'For a single lookup use ask_pipeworx' and 'prefer ask_pipeworx' for breaking/colloquial current-news. Also specifies account prerequisites and depth-mode behavior.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: returns top-N most relevant tools with names, descriptions, full schemas, and curated examples, each result ready to call directly. No contradiction.

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

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

Description is moderately long but front-loaded with purpose and use case. Every sentence adds value; no wasted words. Could be slightly more concise by grouping domain examples, but acceptable for 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?

Covers all essential aspects: what it does, when to use, what it returns (names, descriptions, schemas with examples), and how to call it. Given 30+ sibling tools and no output schema, description provides sufficient context.

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

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

Schema coverage is 100% (all 6 parameters described). Description does not add much beyond schema, but the context about returning top-N and query aliases is helpful. Baseline 3 is appropriate given high schema coverage.

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

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

Description clearly states 'Find tools by describing the data or task' and lists many data domains, distinguishing it from sibling tools. The specific verb 'discover' and resource 'tools' are explicit. It also contrasts with other tools by recommending calling it first.

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

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

Description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides clear context for when to use, though it could be more explicit about when not to use.

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

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

The description adds significant behavioral context beyond the annotations, such as fanning out across multiple sources, returning specific fields, and noting that the patents API may soft-fail. It also aligns with annotations (readOnlyHint, 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 well-structured with examples at the start and a bulleted list of return fields. While it is somewhat lengthy, the examples and details are relevant and helpful, making it efficient for its purpose.

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

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

Given the tool's complexity (multiple source integration, soft-fail scenario) and the absence of an output schema, the description provides comprehensive information about inputs, behavior, and outputs, making it fully 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?

Schema coverage is 100%, providing a baseline of 3. The description adds value by clarifying that type is currently limited to 'company', and that value can be a ticker or zero-padded CIK, not a name. This extra context justifies a score of 4.

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

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

The description clearly defines the tool's purpose: to provide a holistic cross-source profile of a US public company. It includes specific usage examples and explicitly distinguishes itself from chaining multiple single-purpose lookups, making it easy for an agent to understand its unique role.

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

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

The description explicitly states when to use this tool ('when the user asks for a holistic view') and provides alternatives (resolve_entity for names). It also advises against chaining multiple tools, giving clear guidance on when not to use it.

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

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

Description adds 'keyless, offline' beyond annotations, indicating no API keys needed and no network calls. Annotations already cover readOnly and idempotent, so description enriches 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?

Single sentence, direct, and front-loaded with purpose. No redundant 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?

Simple tool with one parameter, full annotations, and output described in the description. No missing information for correct usage.

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

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

Single parameter 'html' with baseline coverage 100%. Description adds no extra meaning beyond 'the HTML' and the tool's purpose; schema does the heavy lifting.

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

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

Description clearly states the verb 'extract' and resource 'hyperlinks from HTML', with output format '{href, text} pairs'. Distinguishes from sibling tools like 'extract_metadata' and 'html_to_text'.

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

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

Implied usage is clear (extract links from HTML), but no explicit guidance on when to use versus alternatives or when not to use.

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

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

The description adds context beyond annotations by specifying the tool is offline, keyless, and extracts specific metadata. Annotations already indicate read-only, idempotent, non-destructive behavior. 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 one sentence, no wasted words, and front-loaded with the action verb. It efficiently conveys the tool's purpose and scope.

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

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

For a simple tool with one parameter, the description covers the main functionality and output types. It could mention the output format, but the purpose is clear given the tool name and sibling 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% with a simple string parameter. The description does not add significant meaning to the parameter beyond what the schema provides. 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 extracts specific metadata types (title, meta description/keywords, Open Graph tags) from HTML. It distinguishes from sibling tools like extract_links and html_to_text, 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 the tool works offline and without keys, which guides usage context. However, it does not explicitly state when to use or not use this tool versus alternatives, though the specificity of metadata extraction is clear.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but does not contradict annotations.

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

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

Two sentences, front-loaded with action, no fluff. Efficient and clear.

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?

Simple tool with one param and no output schema. Description covers purpose, use cases, and sibling relationships. Sufficient for agent decision-making.

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

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

Schema coverage is 100% with a simple 'key' parameter described as 'Memory key to delete'. Description does not add extra meaning beyond the schema.

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

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

Clearly states 'Delete a previously stored memory by key', specifying verb and resource. Differentiates from siblings 'remember' and 'recall' by being the deletion counterpart.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', providing 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the internal process 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 two sentences plus a bulleted list of use cases. It is front-loaded with the main purpose and each sentence adds value. No unnecessary words 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 tool with 2 parameters, good annotations, and no output schema, the description adequately explains the return value ('single text blob ready to drop at site-root/llms.txt') and the process. It is complete for the tool's complexity.

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

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

Schema description coverage is 100% for both parameters (url and max_links). The description does not add parameter-specific details beyond the schema, so the baseline score of 3 is appropriate. It mentions extraction of 'key links' but doesn't elaborate on max_links usage.

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

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

The description clearly states the verb 'generate', the resource 'production-ready llms.txt file for any URL', and the purpose 'so AI crawlers ... can index the site cleanly'. It differentiates from siblings like extract_links and scan_competitor_ai_presence by focusing on the specific llms.txt generation task.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not mention when not to use, but the clarity of use cases compensates.

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

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

The description discloses behavioral details beyond annotations (e.g., dropping scripts/styles, converting block elements) without contradicting annotations. Annotations already indicate safe, idempotent operation, and the description adds specific transformation rules.

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-loading the main action and then detailing specifics. Every sentence adds value without redundancy.

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

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

For a simple tool with one parameter and clear annotations, the description fully covers its purpose, transformations, and ideal use case. No output schema is needed as return value is straightforward.

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 one parameter 'html' described as 'The HTML to convert.' The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool converts HTML to plain text, listing specific transformations (drops scripts/styles/comments, converts block elements to newlines, decodes entities, collapses whitespace). It distinguishes itself from sibling tools by focusing on a specific utility.

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

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

The description provides context by noting it is 'keyless, offline' and 'ideal for cleaning scraped HTML,' implying when to use it. However, it does not explicitly state when not to use it or provide alternatives.

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

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

Annotations already declare safe, read-only behavior. Description adds that it returns active subscriptions by default and mentions return fields, aligning well with annotations.

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

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

Two concise sentences, front-loaded with purpose and return fields. 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 simple list tool with no output schema, description adequately covers return fields, default behavior, and usage 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%, and description does not add parameter details 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?

Clear verb 'List' and resource 'subscriptions'. Specific return fields listed. Does not explicitly distinguish from siblings like subscribe/unsubscribe, but purpose is unambiguous.

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

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

Explicitly advises using this tool to review subscriptions before adding more or to find an ID for cancellation, providing clear use cases.

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

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

Annotations are all false and provide no safety hints, so the description carries the full burden. It discloses concrete behavioral traits: rate-limiting ('5 per identifier per day'), free/no quota impact, that filing without an account returns a claim_token, and that feedback 'affects roadmap' via daily digests. This goes well beyond simple mutation semantics.

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

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

The description is front-loaded with purpose, then flows into usage, exclusions, and claim_token details. Though longer than average, every sentence earns its place—rate limits, quota, and redirects are all critical. It is structured and readable, losing one point for a slightly dense middle section.

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

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

Given the tool has 4 params, a nested context object, and no output schema, the description covers all critical aspects: purpose, exclusions, claim_token flow, rate limits, and a quality bar for the message. The absence of an output schema is compensated by explaining the return token behavior.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant value: it gives a concrete example for claim_token ('pipeworx_feedback({claim_token:"pwfb_…"})'), explains when each feedback type applies, and instructs users to describe issues 'in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This enriches the schema meaning.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from research/query siblings by restricting scope to 'tools served by this Pipeworx connection' and listing feedback categories.

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 (bug, feature/data_gap, praise) and importantly when NOT to use: if the tool came from another MCP server, 'file it with that server instead.' It also explains how to use claim_token for follow-up, satisfying the when-to-use vs alternatives requirement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds caching details (5min-1h), self-aggregating nature, data source (CF analytics-engine), and privacy (no PII), adding value beyond annotations.

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

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

Two efficient sentences covering purpose, uses, and behavioral notes. Not overly concise but well-structured with bullet-like numbered uses.

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

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

Given no output schema, description covers purpose, data sources, caching, and privacy adequately. For a read-only tool with simple input, it provides complete context for agent selection.

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

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

Schema has 100% coverage with enum and description for 'window'. Main description adds usage guidance for different windows. Description adds value beyond schema with use-case-specific advice.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a window. Specific verb-resource pair and distinguishes from siblings by being a trending/social proof tool.

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 lists three use cases (discovering hot data sources, confirming canonical tool, seeing alignment). Provides context for window selection but lacks explicit when-not-to-use or 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 indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral details: monotonicity checks, partition-sum logic, semantic anchor, partition filter, fill check, response structure. 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 detailed and front-loaded with the main purpose. While lengthy, every sentence adds value given the tool's complexity. A slightly more concise version could be possible, but current structure is well-organized.

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

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

The tool has two optional parameters with distinct modes and no output schema. The description fully covers parameters, behavior, output format, and caveats (fill check, semantic anchor, partition filter). Annotations provide safety context. No gaps remain.

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

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

Schema description coverage is 100%, but the description adds significant value beyond the schema: explains event slugs vs topics, provides usage examples, details internal processing logic, and describes the fill_check feature. This greatly exceeds 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 it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific verb+resource, differentiating from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states when to use each parameter: no args for trending scan, event for single-market, topic for cross-event scanning. Provides examples, recommendations (e.g., 'recommended for a specific market'), and warns against trading when fill check fails.

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

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

Beyond the annotations (readOnlyHint, etc.), the description discloses detailed behavioral traits: caching behavior (cached 1h keyed on all knobs), model families, response structure including diagnostics, and exclusions (Fed bets excluded from ranking due to unreliable data). This fully informs the agent about side effects and limitations.

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 verbose (over 500 words) and includes excessive detail about model families that could be in separate documentation. While front-loaded with the purpose, it lacks conciseness and may overwhelm the agent with non-essential technical specifics.

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

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

Despite lacking an output schema, the description covers the response top-level structure (by_segment, fed_candidates, _diagnostics) and explains key fields (edge_pp_net, kelly_fraction). It also documents all parameters and their behavior. However, it does not describe every field in the response with full data types, leaving some ambiguity.

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

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

All 9 parameters are documented in the input schema (100% coverage). The description adds extra context beyond the schema, such as explaining slippage_pp's rationale (zero fees but bid/ask, thin depth) and min_partition_leg_kelly's behavior (why min_kelly doesn't filter partitions). This adds meaningful guidance for an agent.

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 top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by its reliance on Pipeworx data and focus on daily opportunity discovery.

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

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

The description provides clear context for when to use the tool (daily betting discovery) and explains the tradeable-edge knobs (min_liquidity, max_spread_pp) for filtering. However, it does not explicitly mention when to avoid this tool or what alternatives (e.g., polymarket_arbitrage) are better suited for other 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?

Exceeds annotations by detailing response structure, limits (60-day TTL, snapshot start), decay computation (daily closes, not intraday), and inclusion of expired opportunities. 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?

Description is front-loaded with purpose and contains valuable details. While lengthy, every sentence earns its place; minor room for tighter wording.

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

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

Given two optional params, no output schema, and rich annotations, the description fully explains response structure, limits, and field meanings, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. The description adds context like 'snapshot family' for window and default/clamp for days, providing value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes itself from sibling polymarket_edges by focusing on historical tracking rather than 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 explains the tool answers 'how long has this edge existed and is it shrinking?' and provides trade context. While it doesn't explicitly state when not to use, the context implies it's for historical analysis, differentiating it from polymarket_edges.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description aligns with these. Beyond annotations, it discloses return fields (verdict, thin_legs, forced_directional_risk) and behavioral nuances like the risk of partial fills causing directional exposure.

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

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

Well-structured with clear sections (SINGLE-MARKET, BASKET, usage guidance). Every sentence adds value, though slightly verbose; concise for the complexity involved.

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

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

Given the complexity (two modes, no output schema), the description covers inputs, outputs, risks, and usage context comprehensively. It details return fields (vwap_fill_price, slippage_pp, etc.) and risk alerts, making the tool fully self-contained.

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

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

Schema description coverage is 100%, and the description adds significant context: explains how size_usd is interpreted differently in single-market vs basket mode (spend vs proceeds vs settlement notional), default side logic in basket, and the meaning of market/event fields.

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

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

The description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges. It defines two distinct modes (single-market and basket) with specific inputs and outputs.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about risks of partial basket fills converting arb into unhedged directional positions.

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 show read-only, open-world, idempotent, non-destructive. Description adds critical behavioral context: compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and the rarity of tradeable spreads. 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 detailed but every sentence adds value. It is front-loaded with the purpose and modes. Could be slightly more concise, but the density of information is 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 having no output schema, the description comprehensively documents the response structure (leg-by-leg prices, top_spreads_pp, safety fields like compatibility_warning, temporal_alignment, counters). It covers edge cases and warnings thoroughly.

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. The tool description adds context beyond schema: explains modes, override behavior, and mentions that explicit parameters override topic-mapped sides. Provides examples in schema as well.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket, with two modes (topic shortcuts and explicit tickers). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Explicitly explains when to use topic mode vs explicit mode, warns about compatibility issues and temporal alignment, and states that most pre-mapped topics currently return warnings.

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

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

Annotations provide safety profile; description adds scoping by identifier and idempotent read behavior, complementing annotations without contradiction.

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

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

Three concise sentences, no redundancy, front-loaded with core action.

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

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

Completely covers functionality, scoping, and relationships given single optional parameter and no 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?

Schema already covers the parameter; description adds context on omitting key to list all, beyond the schema description.

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

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

Description clearly states the tool retrieves saved values or lists keys, distinguishing it from sibling tools like remember and forget.

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

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

Explicitly describes when to use (look up stored context) and how it pairs with remember/forget, with scope explained.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral context: mark_read sets events as read, affecting subsequent calls. No contradiction found.

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

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

Description is two sentences, front-loaded with core purpose, then adds details. Every sentence contributes meaning—no redundancy or fluff.

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

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

No output schema, but description lists returned fields. Parameters are fully documented. For a read-only list tool with 5 optional parameters, the description provides sufficient context for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances parameter understanding: explains mark_read effect (flag returned events read), gives example values for type ('sec_8k'), and implies ISO format for since. Adds value beyond schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies returned fields (source, citation_uri, raw payload), and mentions filtering options. It distinguishes itself from siblings like 'list_subscriptions' which manages subscriptions, not 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 description says 'Polls work fine' and provides an alternative REST endpoint, indicating when to use this tool versus scripts/dashboards. It lacks explicit when-not-to-use instructions but gives clear context.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description details parallel fan-out to multiple sources, fallback logic, soft-fail for patents, and return structure (changes[], total_changes, citation URIs).

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

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

Single paragraph with efficient front-loading of purpose via examples, followed by concise explanation of behavior and parameters. Every sentence adds unique value.

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

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

Despite no output schema, the description fully covers tool behavior, parameter usage, return fields, and when to avoid this tool. Agent has all necessary information to select and 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?

Schema coverage is 100%, but description adds significant value: explains date formats (ISO and relative), recommends '30d' for monitoring, clarifies value can be ticker or CIK, and notes type is limited to company.

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

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

The description clearly states the tool provides a change feed for a company, covering SEC filings, GDELT/GNews news, and USPTO patents. It gives explicit query examples and distinguishes from sibling tool entity_profile.

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

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

Explicitly tells when to use entity_profile instead, explains fallback behavior (GDELT preferred, GNews on rate-limit), and provides guidance on using '30d' or '1m' for typical monitoring.

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

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

Adds storage details (key-value pair, scoped by identifier, persistence duration for authenticated vs anonymous) beyond annotations. 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?

Well-structured paragraph with core purpose front-loaded. Efficiently covers essential points without verbosity.

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

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

Completely covers usage, behavior, and pairing with siblings. No gaps given the tool's simplicity and full schema coverage.

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

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

Schema coverage is 100%, and description adds practical guidance on key naming patterns and value content, enhancing understanding beyond schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from sibling tools by mentioning recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides pairing with recall and forget, giving clear context and 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 and idempotentHint, and the description adds valuable behavioral context: it returns specific identifier sets per type, includes citation URIs, auto-disambiguates ambiguous inputs, and cascades through multiple internal lookup endpoints. It does not mention failure modes or latency, but this is not critical for a read-only resolver.

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 example queries, immediately conveys the core purpose, and then efficiently lists supported types with their return details. Every sentence carries informative weight; no filler or repetition.

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

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

Given the tool has no output schema, the description compensates by specifying the exact return fields for each type (ticker, CIK, company_name; RxCUI, ingredient, brand) and even the citation URIs. It also clarifies the internal multi-lookup mechanism. This is a complete picture 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?

The schema already provides descriptions for both parameters (type and value) with 100% coverage. The description enriches this by detailing accepted formats (e.g., ticker 'AAPL', CIK '0000320193', drug names like 'ozempic') and explaining what each type returns, adding meaning beyond the bare 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 multiple concrete example queries ('What's the ticker for…', 'find the CIK for…') and clearly states the tool resolves a user-spoken name to a canonical identifier. It explicitly distinguishes itself from siblings by noting the IDs are required as input by other tools, which differentiates it from 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?

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also outlines the two supported types and what inputs are accepted. However, it does not explicitly name alternative tools for cases when the ID is already known, so it falls short of full exclusionary guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds internal workflow: probes each entity with ai_visibility_check, ranks by score. No contradiction.

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

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

Single paragraph with 3-4 sentences, front-loaded with main action. No fluff, every sentence adds value.

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

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

No output schema, but description explains return format: 'ranked list with score, confidence, signal density per entity'. Also covers prerequisites (models, apiKey), context, and entity count (2-8). Complete for a tool with comprehensive annotations.

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 value: explains first entity as 'subject', gives examples for 'context', and clarifies usage of 'models' and '_apiKey'. Goes beyond 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?

Clearly states the verb 'Compare', resource 'AI visibility across multiple entities', and outcome 'ranked list'. Distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (different comparison).

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

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

Explicitly mentions usage in 'competitive AI-marketing audits' with an example question. Implies when not to use (single entity check) and suggests alternative siblings.

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

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

Annotations already indicate safe, idempotent read. Description adds critical behavioral detail: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed list is included on timeout. Adds value beyond annotations.

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

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

Description is front-loaded with purpose and efficiently structured. Some minor verbosity (e.g., 'NPM ecosystem only in v1; ... fall under deps.dev:version directly') is acceptable to convey constraints. Slightly wordy but earns its sentences.

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 return fields (summary block, advisories, links, alternative versions). Covers edge cases like partial failures, scoped packages, and default version behavior. Completeness is high.

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

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

Schema covers both parameters with descriptions (100% coverage). Description echoes the scoped package acceptance but doesn't add new semantic meaning. 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?

Clearly defines the tool as a composite check for npm packages, combining data from deps.dev and bundlephobia. It specifies the exact question it answers ('should I add this npm package'), making it distinct from sibling tools.

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

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

Explicitly states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and ecosystem limitations (NPM only in v1), with reference to alternative tools for other ecosystems. Provides clear usage boundaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds rich behavioral detail: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and each passage includes character offsets for verification. Goes well beyond annotations.

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

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

Front-loaded with key purpose, then use case, then pairing, then technical details. Efficient but could be more scannable with breaks. Every sentence adds value, no redundancy.

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

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

Covers input, output (top-N passages with offsets and scores), use case, pairing, algorithm, window size, char cap, and truncation behavior. No output schema, but description adequately explains return values. Complete for a retrieval tool of moderate 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 detailed descriptions (max chars for text, 1-20 range for limit, NL examples for query). Description adds little beyond schema: it provides context on how query works (natural-language) and mentions limit default, but these are already in 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?

Clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result). Distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded and contrasting with whole-document retrieval.

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

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

Explicitly says when to use: when the record is too large to fit in the prompt, saving context. Suggests pairing with ask_pipeworx_grounded, but does not explicitly state when not to use or list alternatives beyond that pair.

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 fully discloses behavioral traits: write operation (creates subscription), idempotent (annotation), and non-destructive. It adds critical context beyond annotations: requires OAuth, returns ID, delivery constraints (SMS cap, webhook auto-disable after 10 failures, phone verification needed). 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 well-structured with a clear lead sentence, then requirements, types, and delivery details. It is slightly verbose on webhook HMAC steps but remains efficient and front-loaded.

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

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

The tool is complex with 3 parameters (one nested object) and no output schema. The description covers prerequisites, all subscription types with parameter examples, return values, and delivery constraints with error handling (auto-disable). It is thorough for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds concrete examples for each subscription type (e.g., sec_8k items, polymarket_edge topic) and explains nested delivery fields (webhook secret, HMAC). This enhances understanding beyond the schema's 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 states a specific verb ('Create') and resource ('proactive monitoring subscription'), and includes the return value ('Returns the new subscription id'). It clearly distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description explicitly mentions the requirement for a Pipeworx OAuth account, lists supported types with examples, and details delivery channels. However, it does not explicitly state when to avoid using this tool or direct users to alternatives (e.g., manage existing subscriptions via list_subscriptions/unsubscribe), though context signals provide sibling names.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, and idempotentHint=true. The description adds context about returning category-bucketed questions with tool+argument shapes from a live catalog, which is valuable beyond 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 a single paragraph but well-organized: starts with example queries, explains output, then usage options. Every sentence adds value. Could be slightly more structured (e.g., bulleted examples) but remains concise and front-loaded.

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

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

With one optional parameter and no output schema, the description fully explains the purpose, input options, and return format (category-bucketed questions with tool+argument). No additional information is needed for an agent to use this 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 a single optional 'topic' parameter. The description repeats the schema description but explicitly lists the allowed values (finance, pharma, etc.) and clarifies behavior when omitted, adding helpful detail beyond the schema's generic description.

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

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

The description clearly states the tool as the onboarding entry point for agents to learn about Pipeworx's capabilities. It uses specific verbs ('suggest', 'returns') and identifies the resource (category-bucketed example questions). It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by positioning itself as the first tool to use.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides guidance on calling with no arguments or with a topic. Does not explicitly state when not to use, but the positive guidance is strong and includes alternative tools implicitly.

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

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

Discloses beyond annotations: row is deactivated not deleted, historical events remain. Annotations indicate mutation but not destructive; description adds concrete behavior.

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

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

Two efficient sentences with no wasted words. Front-loaded with purpose, followed by behavioral nuance.

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?

Complete for a simple tool: covers purpose, ownership, deactivation behavior, and links to recent_alerts. No gaps given schema and annotations.

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

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

Schema coverage is 100%, so baseline 3. Description adds no additional meaning to the 'id' parameter beyond what the schema already provides.

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

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

Description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tool 'subscribe' which creates subscriptions.

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

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

Explicitly states ownership enforcement, telling agents only to cancel own subscriptions. Does not explicitly mention alternatives but context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral detail: for financial claims it uses exact percent-delta math via SEC EDGAR; for others it uses a grounded pipeline with verbatim evidence. It also explains the return value structure (verdict, value with citation, reasoning).

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

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

The description is well-structured, starting with query examples, then usage, then technical details. While somewhat lengthy, each sentence adds value. It is front-loaded with key phrases.

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

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

The description covers all essential aspects: purpose, when to use, behavior, parameter semantics, and return values. There is no output schema, so the description compensates by explaining the verdict, value, and reasoning. It is thorough.

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 parameters. The description adds extra meaning beyond schema: it explains that tolerance_pct overrides implied tolerance and that the default is capped at 5. This is valuable context.

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's purpose: natural-language claim verification against authoritative sources. It lists concrete verb phrases like 'fact check', 'verify the claim', and distinguishes from siblings by noting it replaces 4-6 sequential calls.

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

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

The description provides clear usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates between financial and other claims, implying when to use. It doesn't explicitly state when not to use, but the guidance is sufficient.

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