Gtin

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: default model choice, billing model for Anthropic calls (BYO key), return structure (per-model score, confidence, signals, raw_response + combined view). No contradictions with annotations.

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

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

The description is concise (3 sentences) and well-structured: first sentence states core purpose and default, second covers optional probing, third summarizes return and use cases. No superfluous information.

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

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

All aspects are adequately covered: purpose, parameter details (defaults, optionality, billing), return format, and use cases. Despite no output schema, the description provides sufficient return structure. Complexity is moderate with 4 params, and the description compensates well.

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%, providing a baseline of 3. The description adds meaning beyond schema by explaining the default model (Workers AI Llama-3.3-70b) and the billing arrangement for the _apiKey parameter, plus clarifying the context parameter's disambiguation purpose.

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 'probe' and resource 'LLMs for entity knowledge', scoring visibility 0-100 per model. It distinguishes from sibling tools like scan_competitor_ai_presence by specifying use cases for AI-marketing audits, pre-launch checks, and competitive monitoring.

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 (AI-marketing audits, brand checks, competitive monitoring) and explains the default model vs. requiring an API key for Anthropic. However, it does not explicitly state when not to use it or mention alternatives among sibling tools.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already cover safety profile. The description adds meaningful behavior: it routes across 5,501 tools, fills arguments, returns stable pipeworx:// citation URIs, and works on every tier. This goes beyond annotations without contradicting them, but does not detail any potential delays or failure modes.

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

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

The description is longer than ideal but every sentence contributes: preference guidance, alternative tool comparisons, concrete examples, and context about routing. It is front-loaded with 'PREFER OVER WEB SEARCH' and organized to lead with the most critical information. Length is justified by the tool's broad 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?

Given no output schema, the description explains the return format (structured answer with stable citation URIs). It covers the tool's role as a router, its coverage scope, when to escalate to other tools, and example use cases. The description is complete for an opening tool with rich 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 aliases and an example for the single required parameter. The description does not add parameter-level syntax beyond schema, but its example questions (e.g., 'current US unemployment rate') provide practical usage context. Baseline of 3 is appropriate since the schema carries the semantic load.

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

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

The description clearly states the tool routes questions to a vast array of sources and returns structured answers with citations. It uses specific verbs (routes, fills, returns) and distinguishes itself from named alternatives like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

Explicit usage guidance is provided: 'PREFER OVER WEB SEARCH' for factual questions, 'START HERE' as default, and 'Step up only when needed' with concrete alternative tools. Example queries illustrate when to use it, and the description notes it works even when web search could answer, giving clear decision rules.

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

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

Beyond the annotations, the description discloses key behavioral traits: that this is a beta with 'candidate routing improvements enabled live whenever one is under test', that 'No candidate is active right now' so it matches ask_pipeworx exactly, and that it 'Falls back to nothing — this IS a full working router'. This adds experimental status and current equivalence context, which is valuable and not present in the 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?

The description is a few sentences long and front-loaded with the core identity ('Beta version of ask_pipeworx'). Each sentence adds context (beta status, current state, usage, comparison process, fallback nature). It's somewhat verbose but not wasteful, earning a 4.

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 the essential context: what the tool is (beta router), current behavior (matches ask_pipeworx), usage intent (newest routing), and that it's a full router. Since there is no output schema, it references 'same response shape' as ask_pipeworx, which is a helpful pointer but doesn't detail the shape. It is complete enough for an experimental router, though slightly cryptic about the response format without prior knowledge of ask_pipeworx.

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 all six parameters described as aliases for 'question', so the schema already documents parameter semantics thoroughly. The description adds only 'same arguments' referencing ask_pipeworx, which is not additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,501 tools, and explicitly distinguishes it from the stable ask_pipeworx by stating 'identical universal router ... with candidate routing improvements'. It answers what the tool does: it routes questions to tools, with experimental routing changes. This is specific and differentiates it from siblings.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing'. It also explains the alternative by referencing the stable router and notes results are compared against it. This tells the agent when to choose this tool over ask_pipeworx (when experimental routing is desired) and provides context that it currently behaves identically.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing specific refusal behaviors, a defined set of refusal_reason values, the extra LLM call cost, and the constraint that answers are extracted only from the tool result. It also details the success response structure, adding significant behavioral clarity.

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

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

The description is dense but every sentence adds value. It front-loads the key concept (hallucination-resistant) and succinctly covers routing, extraction behavior, return structure, usage guidance, and the cost tradeoff. Slightly long, but not verbose; it earns its length.

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

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

Without an output schema, the description fully compensates by documenting the success response fields (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reason values. It also covers the cost implication and provides usage context, making the tool fully understood without other documentation.

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

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

Schema description coverage is 100% (all parameters documented, including aliases). The description adds no semantic detail beyond the schema, but since the schema already fully explains the parameters, the baseline of 3 is appropriate. The description's mention of 'question in natural language' merely restates the schema.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb+resource. It explains that it routes like ask_pipeworx but then extracts the answer solely from the tool result, and it differentiates from the sibling tool by noting the extra LLM call and the 'prefer ask_pipeworx for casual lookups' guidance.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' followed by concrete high-stakes examples. It also contrasts with the sibling tool by stating 'prefer ask_pipeworx for casual lookups,' giving clear when-to-use and when-not-to-use 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?

The description extensively details behavioral traits such as market resolution, classification, fan-outs, response shapes, safety mechanisms, and edge cases. This goes far beyond the annotations (readOnlyHint, etc.), providing comprehensive transparency.

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

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

The description is lengthy but well-organized with multiple informative sections. It could be more concise, but every sentence adds value, making it effective for an AI agent.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers input forms, response structure, safety, edge cases, and behavioral details thoroughly. It leaves no gaps for an agent's understanding.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the 'depth' parameter (quick vs thorough) and 'include_raw' parameter effect, enhancing understanding 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 explicitly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists specific use cases like 'should I bet on X', distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides clear use cases and examples of when to use the tool, but does not explicitly state when not to use it or mention alternatives. However, the context of sibling tools helps 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?

Adds significant context beyond annotations: describes data sources (SEC EDGAR, FAERS), handles off-calendar fiscal years, mentions sorting by primary metric, and states it returns citation URIs. No contradiction with annotations.

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

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

Front-loaded with query examples, each sentence adds value. Slightly verbose but appropriate for the complexity; no redundant information.

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

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

Covers all necessary aspects: purpose, usage, data sources, sorting, output format (paired data + citation URIs), and edge cases (off-calendar fiscal years). No output schema, so description adequately explains return structure.

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

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

Schema coverage is 100%, but the description adds meaning by explaining what each enum value ('company' vs 'drug') pulls and gives examples for the 'values' parameter. This enriches the schema beyond the baseline.

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

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

The description clearly identifies the tool as for side-by-side comparison of 2-5 companies or drugs, with specific verbs like 'compare' and examples of user queries. It distinguishes from siblings like entity_profile by noting it replaces multiple lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance and naming the alternative approach.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses crucial behaviors: account/paywall requirements, that it returns gaps[] rather than inventing answers, the second-hop iteration for standard/thorough depths, the inclusion of contradictions[], and the condition that citation_uri is only present when resolvable. It also states that large records are semantically excerpted, not head-truncated, and gives expected latency. These are substantial additions well beyond annotation hints.

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

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

The description is dense and long, with numerous parenthetical asides and multiple caveats packed into one paragraph. While every sentence carries information, the structure makes it harder to scan. It could be broken into bullet points or sub-sections (e.g., when to use, output details, depth behavior) to improve readability without losing content.

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

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

Given the tool's complexity and absence of an output schema, the description fully explains the return format: findings packet with evidence, confidence, source, fetched_at, citation URI, gaps[], contradictions[], and hop field. It also covers practical details like depth level effects, account tiers, latency envelopes, and edge cases (current news returns empty gaps). This is comprehensive and leaves almost no ambiguity about behavior and outputs.

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

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

Schema coverage is 100% for both parameters; the schema already describes the question and depth attributes in detail, including enum meanings. The description adds some illustrative context for the question parameter ('compare X and Y...') but doesn't meaningfully extend the parameter semantics. It mostly reinforces what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources' in one call, and explicitly contrasts with open-web search. It also distinguishes from siblings by noting that for single lookups or breaking news, ask_pipeworx is preferred. The purpose is unmistakable and differentiated.

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

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

The description provides explicit guidance on when to use this tool: 'Best for broad/multi-part questions over structured data.' It also names alternatives and exclusions: 'For a single lookup use ask_pipeworx' and for breaking/current-news topics prefer ask_pipeworx. It even notes the account requirement and that unauthenticated users should use ask_pipeworx instead.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds beyond this by detailing the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This is rich context that helps the agent understand the behavioral outcome without contradicting annotations.

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

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

The description is well-structured and concise. It front-loads the core purpose and use cases in the first sentence, then provides additional details on return format and when to call it. Every sentence adds value without redundancy. It is appropriately sized for the tool's complexity.

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

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

Given the tool's role as a discovery tool with 100% schema coverage and safety annotations, the description covers what an agent needs to know: purpose, usage guidance, and return format. It doesn't detail ranking or ambiguity handling, but for a tool of this complexity, it is sufficiently complete. A 5 would require more specifics on edge cases.

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

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

Schema description coverage is 100%, with all parameters documented. The description adds value by listing the multiple aliases for the query parameter (q, task, search, description) and providing examples. It also explains the limit parameter's default and max. This goes beyond the schema's baseline, making it a 4.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the verb (find/discover) and resource (tools). The description also distinguishes itself from sibling tools by explicitly positioning it as a discovery tool for browsing available tools, which is distinct from specific research or utility tools like deep_research or validate_gtin.

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

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

The description provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists domains where the tool is useful (SEC filings, financials, etc.), helping the agent decide when to use it. However, it does not explicitly state when not to use it or mention alternatives, which would make it a 5.

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

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

The description discloses behavior beyond annotations: parallel fan-out across multiple sources, soft-fail for patents, GDELT→GNews fallback, return fields with specifics, and no output schema 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 dense but well-structured with examples up front. Every sentence adds value, though it could be slightly more concise given the length.

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

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

Despite no output schema, the description fully covers return fields, source behaviors, limitations, and fallbacks, 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 for both parameters. The description adds context (e.g., zero-padded CIK, names not supported) and cross-reference to resolve_entity, enhancing comprehension.

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

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

The description uses specific verbs ('profile', 'fans out across...') and clearly identifies the resource ('US public company'). It distinguishes from sibling tools like resolve_entity by specifying that names are not supported.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack lookups' for holistic views and provides a when-not-to-use instruction ('use resolve_entity first if you only have a name').

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. The description adds usage context but does not discuss idempotency or error behavior beyond what annotations imply.

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

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

Two sentences: first states purpose, second provides usage guidance. 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?

For a simple one-parameter tool with annotations present, the description fully covers purpose, usage, and sibling pairing.

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

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

Schema coverage is 100% and the description simply echoes the parameter's purpose without adding new semantics. Baseline 3 applies.

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

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

The description clearly states the action (Delete) and resource (previously stored memory by key), and it distinguishes from sibling tools like remember and recall.

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 (context stale, task done, clear sensitive data) and pairs with remember and recall for context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false/true, so the safety profile is clear from annotations. The description adds that it fetches the page, extracts title/description/links, and outputs standard markdown. This aligns with annotations, but does not disclose any surprising behavior beyond what is obvious. The description adds moderate context but not enough to raise the score higher given annotation coverage.

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 that front-loads the main purpose. It is concise but could be slightly more structured (e.g., bullet points for use cases). Every sentence adds value, and there is no fluff. Scoring 4 instead of 5 due to minor structural improvement possible.

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 (2 parameters, simple read-only behavior, no output schema), the description fully covers what the tool does, what it fetches, what format it outputs, and common use cases. It is complete for an AI agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with both parameters described in the schema. The description mentions the URL and implies a limit on links (max_links) but does not add significant meaning beyond the schema. Baseline score of 3 is appropriate since the description does not compensate for any gaps.

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

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

The description clearly states the tool generates a production-ready llms.txt file, using verbs 'generate', 'fetches', 'extracts', and 'emits'. It specifies the resource (llms.txt) and distinguishes from sibling tools by listing concrete use cases (indexing client sites, drafting for own project, auditing competitor).

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for one's own project, or auditing a competitor. It implies when to use this tool versus alternatives, but does not explicitly state when NOT to use it, which would strengthen the guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so safety and idempotency are clear. The description adds minimal behavioral context beyond the algorithm (mod-10). No contradictions.

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

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

Two sentences, front-loaded with core action, no wasted words. 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?

For a simple computational tool with one parameter and rich annotations, the description covers purpose and usage. It could mention the return value format, but is adequate.

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

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

Schema coverage is 100% with a clear description of the 'data' parameter. The description reinforces that it should be digits except check digit, but adds little beyond the schema.

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

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

The description clearly states the tool computes the mod-10 check digit for GTIN/EAN/UPC data digits, excluding the check digit itself. It distinguishes from the sibling tool 'validate_gtin' which validates the full GTIN.

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 to generate or repair a barcode,' providing clear context. It does not explicitly list when not to use, but the sibling tools imply 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 readOnly, idempotent, non-destructive. Description adds contextual detail about return fields and scope. No contradictions.

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

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

Two sentences, front-loaded with purpose and return format, followed by usage guidance. No extraneous 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 simple tool (one optional param, no output schema), the description fully covers purpose, return format, and usage. No missing information.

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

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

Schema coverage is 100% with a clear description for the only parameter. Description implies default behavior (active only) but adds no new 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 it lists 'the caller's active subscriptions' and specifies the return fields. Distinguishes from sibling tools like subscribe and unsubscribe by being a read operation.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel,' indicating when to use it versus alternatives.

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

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

All annotations are false, so description carries the behavioral burden. It discloses rate limiting (5/day/identifier), quota exemption, claim_token mechanics for follow-up, and a 'don't paste the end-user's prompt' rule. This adds real behavioral context beyond the bare false 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?

Dense, front-loaded purpose and organized sections. Each sentence earns its place (exclusions, token flow, rate limits), though length is on the higher side for a simple feedback tool.

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

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

Given the moderate complexity (4 params, nested object, no output schema), the description covers the full workflow: what to submit, how to frame it, follow-up via claim_token, and expectations (rate limit, quota). Ambiguity exists about account-based responses, but core usage is 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?

Schema covers 100% of parameters with descriptions, so baseline is 3. Description adds minor context (example claim_token call and guidance to describe issues in terms of Pipeworx tools/packs), but doesn't substantially elevate semantics 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?

Description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb and resource. It clearly distinguishes itself from sibling research tools by framing actionable feedback categories (bug, feature, data_gap, praise).

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: for bugs, feature/data_gap requests, or praise. It gives an exclusion criterion: only for tools served by this Pipeworx connection, and directs other-server issues elsewhere, with a disambiguation ('Not sure? Pipeworx tool names are the ones this connection lists').

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 valuable behavioral context beyond annotations: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h). Annotations already signal safety (readOnly, idempotent, not destructive), and description complements 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?

Concise and well-structured: two sentences for core function, bulleted use cases, and a final line on data source and caching. Every sentence serves a purpose with no redundancy.

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

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

Given simple input schema (1 optional param) and no output schema, the description fully covers what the tool returns (top tools, packs, volume) and usage context. Caching and non-PII nature further inform agent behavior. No gaps.

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

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

Schema has 100% coverage for the single parameter 'window' with enum and description. Description adds value by explaining the semantic difference between short and long windows (hot vs. steady-state demand). Baseline 3 elevated to 4 for extra guidance.

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 returns top tools, top packs, and total call volume over a window, with three clear use cases. It distinguishes itself from sibling tools by focusing on trending data rather than discovery or other functions.

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 three explicit use cases for when to use the tool. It does not mention when not to use, but the context of trending vs. historical is implied by window choices. Slightly missing explicit exclusion criteria.

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 extensive behavioral context: monotonicity violations, partition checks, Jaccard similarity filtering, placeholder filtering, and fill check against CLOB depth. No contradiction with annotations.

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

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

The description is long but well-structured into paragraphs with clear sections. It is front-loaded with the main purpose and modes. Some details (e.g., Jaccard threshold, placeholder fraction) could be more concise, but overall it is efficient for the complexity.

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

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

Given the tool's complexity and lack of output schema, the description covers modes, partition checks, fill checks, and response structure. It lacks explicit error handling or limitations, but for a read-only analysis tool, it provides sufficient context for an AI agent to use it correctly.

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

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

Schema description coverage is 100%, but the description adds significant value: for 'event' it explains walking child markets and partition checks; for 'topic' it explains cross-event scanning and Jaccard similarity. Examples of acceptable values are provided, enhancing understanding 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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with concrete examples. While sibling tools exist, the description's specificity differentiates it effectively.

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: 'Call with NO args for a trending_scan', 'pass event for...', 'topic for...'. It recommends event mode for specific markets and topic for cross-event scanning. It also advises when not to trade (if realizable_edge_pp ≤ 0) and mentions polymarket_fill_risk for custom sizing.

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 far exceeds the annotations by detailing internal model logic (e.g., 'lognormal barrier from 90d FRED log-returns', 'partition_overround with favorite-longshot bias correction'), edge calculation, caching strategy (1h KV-level), and output structure including diagnostics for empty segments. No contradictions with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

The description is long but well-structured, starting with the purpose, then dividing into model families, response fields, and knob explanations. Every sentence adds meaningful detail. However, it could be more concise by condensing some technical explanations. The front-loading of purpose is effective.

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

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

Given the complexity (9 parameters, no output schema), the description thoroughly explains the response shape: by_segment with three segments, fed info, and diagnostics. It covers what each segment contains, edge metrics, and why certain edges are excluded. This compensates for the lack of output schema and ensures agents understand the full 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?

All 9 parameters have schema descriptions (100% coverage). The tool description adds value by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining their practical effect (e.g., 'drop opportunities where edge isn't realizable'). It also clarifies parameter behavior (e.g., min_kelly applies to single-leg, min_partition_leg_kelly to per-leg). This contextual guidance goes 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 starts with a clear verb+resource combo: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly states the tool's purpose and its intended use case ('what should I bet on today'). The detailed breakdown of three model families and response segments further clarifies the specific outputs, distinguishing it from broader market tools.

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

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

The description implies usage context ('agents discover opportunities without paging hundreds of markets') and provides adjustment knobs, but it does not explicitly state when to use this tool versus alternatives like polymarket_arbitrage or polymarket_edge_tracker. No 'when-not-to-use' or explicit exclusions are provided, though it does note Fed bets are excluded and why.

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

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

Annotations already set readOnlyHint and idempotentHint to true; the description adds rich behavioral context: it reads from snapshots, returns tracked/expired/snapshot_dates, explains decay computation, and notes limits (60-day TTL, daily closes). 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 dense but effective. It front-loads the purpose and uses clear structure (RESPONSE: with subparts, LIMITS). Minor improvement: could use bullet points for readability, but no wasted 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?

Given the tool has 2 optional parameters, no output schema, and moderate complexity, the description fully covers what the tool does, what it returns, and limitations. It is self-contained for an agent to decide 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%, baseline 3. The description adds value by explaining 'days' as lookback with clamp range and 'window' as snapshot family with defaults. It provides more context than the schema alone.

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

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

The description states a specific verb-resource pair: 'Edge persistence and decay telemetry' from 'daily polymarket_edges snapshots'. It answers a concrete question and implicitly distinguishes from the sibling 'polymarket_edges' by focusing on historical time-series and decay analysis.

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

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

It explains the tool answers 'how long has this edge existed and is it shrinking?' and gives a concrete example contrasting fresh vs old edges. However, it does not explicitly state when NOT to use it or name alternative tools (beyond 'polymarket_edges'), which would strengthen this dimension.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. Description adds rich behavioral context: walks the ladder, returns fill details, and warns that partial basket fills convert arb into unhedged directional position—the dominant loss mode. 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?

Dense and informative, but could be more structured (e.g., bullet points). Every sentence earns its place, but length is justified by complexity. Front-loaded with key 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?

No output schema, but description lists all return fields for both modes, explains risk scenarios, and covers edge cases. Complete for a tool of this complexity.

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

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

100% schema coverage, but description adds value: explains basket mode default side logic, size_usd clamp (10–1,000,000), and difference between market and event parameters. 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?

Description specifies a 'realizable-vs-theoretical edge check against live CLOB order-book depth' with clear single-market and basket modes. It distinguishes from siblings by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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 when to use: before acting on arbitrage signals or trades above $500. Explains why not to use for thin books or partial fills due to directional risk. Clearly differentiates from sibling tools.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds substantial context: explains two modes, response structure, safety fields (compatibility_warning, temporal_alignment), and mathematical meaning. Discloses that real spreads are rarer than shortcuts suggest. 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?

Description is quite long and contains redundant detail (e.g., compatibility_warning explained twice). While front-loaded with purpose, the verbosity reduces conciseness. Some trimming would improve readability.

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

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

Despite no output schema, description fully explains response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). Addresses edge cases and limitations. Complete for a tool with 3 optional parameters and complex 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 covers all 3 parameters (100% coverage). Description adds meaning: explains topic mapping, how explicit parameters override, and interplay between them. 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?

Description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like 'polymarket_arbitrage' by focusing on cross-venue spread. Two modes and response fields are explicitly mentioned.

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 provides two modes (topic shortcuts and explicit tickers) and warns about compatibility issues. Provides examples of topics. However, it does not directly compare to sibling tools like 'polymarket_arbitrage' to guide when to use this vs 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=true and idempotentHint=true, so description adds context about listing all keys when no argument is provided and scoping to identifier. 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 concise with three sentences, front-loaded with the main action, and no unnecessary words.

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

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

Given the simple parameter (1 optional string) and no output schema, the description explains both retrieval and listing use cases completely. Could mention return format but not required.

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

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

Schema coverage is 100% and the description adds usage context (omit to list all keys) but doesn't provide additional parameter details 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 retrieves a value saved via remember or lists all keys when omitted. It distinguishes from sibling tools 'remember' and 'forget', and specifies the resource ('memory key').

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

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

It explicitly states when to use (look up stored context) and pairs with remember and forget. It also mentions scoping and gives examples of use cases (target ticker, address, research notes).

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 states 'Set mark_read:true to flag returned events read,' implying a state change (marking as read) that contradicts the readOnlyHint: true annotation. Annotations indicate no modifications, but the description explicitly describes a write-like side effect. This is a clear 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 four sentences, front-loading the core purpose. Every sentence adds value: purpose, return fields, filtering, mark_read behavior, and alternative access. No fluff or redundancy.

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

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

Given no output schema, the description adequately describes return fields (source, citation_uri, payload) and covers key behaviors (polling, alternative endpoint, mark_read semantics). It lacks details on error handling or pagination beyond the 'limit' parameter, but is otherwise complete.

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

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

Schema coverage is 100%, but the description adds meaningful context beyond schema descriptions: it provides an example for 'type' ('sec_8k'), explains the purpose of 'mark_read' (so next call shows newer events), and relates 'since' to ISO timestamps. This enhances understanding beyond the schema alone.

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

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

The description clearly states 'Pull fired events from your subscription feed,' specifying a verb and resource. It distinguishes itself from siblings like 'list_subscriptions' by focusing on events rather than subscription details, and mentions an alternative HTTP endpoint for scripts, further clarifying its niche.

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 polling suitability and points to an alternative HTTP endpoint for scripts/dashboards, giving clear guidance on when to use this tool vs. manual access. It does not explicitly contrast with other tools like 'recent_changes,' but the context is sufficient for most 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?

Disclosed behavioral details beyond annotations: fans out to SEC EDGAR, GDELT→GNews fallback on rate limit/5xx, USPTO soft-fail due to API sunset. Annotations indicate readOnlyHint=true (safe read) and idempotentHint=true, which are consistent.

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

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

The description is dense but not verbose. Every sentence provides necessary information: purpose, examples, behavior details, parameter formats, and sibling differentiation. Front-loads the core purpose with query examples.

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

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

Despite no output schema, the description explains the return structure (changes grouped by source, total_changes count, pipeworx:// citation URIs). It covers all needed context for a complex multi-source tool with fallback behavior, leaving no major gaps.

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

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

Schema description coverage is 100% for all 3 parameters, so baseline is 3. The description adds value by explaining the 'since' parameter formats ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring, which goes 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 'change feed for a company' with explicit query examples ('What's new with X', 'latest on Y'). It distinguishes from sibling entity_profile by specifying that entity_profile is for static profiles regardless of window.

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

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

Provides explicit guidance on when to use this tool ('for a company in the last N days/weeks/months') and when to use the sibling tool entity_profile instead. Includes example queries that clarify the use case.

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

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

Beyond annotations (idempotentHint=true, etc.), description adds key behavioral details: persistence behavior varies by authentication (permanent vs 24-hour), and scoping by identifier. 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?

Four sentences starting with purpose, then usage, then behavior details. No redundant or unnecessary content. Every sentence is informative and earns its place.

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

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

Given simple input schema (2 required string params) and no output schema, the description fully covers purpose, usage, persistence, and relationships to sibling tools (recall, forget). No gaps.

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

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

Schema has 100% coverage with descriptions. Description adds naming conventions for keys (e.g., 'subject_property') and clarifies value is free text. Adds value beyond schema but schema already does most work.

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 specifies the verb ('Save data') and resource ('memory') with concrete examples ('resolved ticker, target address'). It distinguishes from sibling tools recall and forget, making the purpose clear.

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 you discover something worth carrying forward') and provides use cases. Notes pairing with recall/forget for retrieval and deletion, giving clear context for alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: return payloads (ticker, CIK, company_name; RxCUI, ingredient, brand), auto-disambiguation, internal cascading through multiple endpoints, 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 somewhat long but well-structured: example queries first, then usage directive, then per-type details. Every sentence contributes useful information, and the SUPPORTED TYPES section organizes details effectively. It avoids fluff, though it could be tightened slightly.

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

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

Given there is no output schema, the description compensates by specifying exact return fields for both entity types, naming source systems (SEC EDGAR, RxNorm), and mentioning citation URIs. It also notes the internal cascade and efficiency benefit. This is sufficient for a moderately complex read-only lookup tool.

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

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

Schema covers both parameters with descriptions and enumerations, achieving 100% coverage. The description goes further by explaining accepted input formats for each type (ticker, CIK, name vs. brand/generic) and detailing the outputs each type returns, adding meaning beyond the schema.

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

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

The description clearly states the verb 'resolve' with the resource 'user-spoken NAME to canonical/official identifier.' It distinguishes from siblings by noting that other tools require this ID as input and by explicitly saying 'Use FIRST whenever you have a name but need an ID.' Examples of user queries further clarify intent.

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

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

Provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' This is strong contextual direction. However, it does not explicitly state when not to use the tool (e.g., if an ID is already known) or name alternate sibling tools as fallbacks, though the first-use directive covers most 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?

The description explains the tool probes each entity with ai_visibility_check, which is a specific behavioral trait. It also describes the output format (ranked list with score, confidence, signal density). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description is consistent and adds context beyond them.

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

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

The description is two sentences plus a parenthetical use-case note, all front-loaded and free of fluff. Every sentence provides essential information.

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

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

Despite no output schema, the description covers the return format (ranked list with score, confidence, signal density) and explains the probing process. For a 4-parameter tool with full schema coverage, it is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that the first entity is treated as the 'subject' for narrative, which is additional meaning beyond the schema description for the 'entities' parameter.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying its competitive audit purpose.

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

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

The description provides a concrete use case: 'competitive AI-marketing audits: does Claude know about us as well as our competitors?' This tells when to use the tool, though it does not explicitly mention when not to use or suggest alternatives like individual ai_visibility_check calls.

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, destructiveHint false. Description adds valuable behavioral context: composite call fans out, partial failures degrade gracefully, bundlephobia first measurement may take 5-30s and will be listed in sources_failed if timed out.

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 detailed but every sentence adds specific information: purpose, usage, return structure, ecosystem limitation, failure behavior. Could be slightly more concise but is well-structured and informative.

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

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

Despite no output schema, description lists all return fields (summary block fields: is_latest, license, published_at, etc.), per-advisory detail, links, alternative versions. Covers inputs, behavior, and outputs completely for a two-parameter tool.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds that scoped packages are accepted and version defaults to latest, providing minor extra value beyond schema.

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

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

Description clearly states the composite purpose: 'should I add this npm package to my project' check aggregating deps.dev and bundlephobia data. It distinguishes itself from siblings by being the only dependency scanning 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?

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes ecosystem limitation and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds embedding model (BGE-base-en), method (cosine over 500-char overlapping windows), char cap (200K chars truncated with flag), and that passages have offsets for verification.

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 core action. Efficiently packs use case, behavioral details, limits, and sibling reference without 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?

Tool has 3 parameters, no output schema, no nested objects. Description covers purpose, when to use, behavioral details (model, method, limits), parameter specifics, and sibling integration. Complete for this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds context: 'max ~200K chars' for text, 'default 5' for limit, and example queries for query parameter. This 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 it performs semantic search inside a fetched record, specifying input (text and query) and output (top-N passages with offsets and similarity scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Mentions alternatives and integration: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document'.

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 detailed behavioral context: persistence requirement, delivery limits, webhook signing secret, auto-disable after failures. However, it contradicts the idempotentHint annotation by implying each call creates a new subscription, which is not idempotent.

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 comprehensive and well-structured with examples and options. While it is relatively long, the complexity justifies the detail; every sentence serves a purpose.

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

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

Given the lack of output schema and nested objects, the description covers all necessary aspects: subscription types, parameters, delivery channels, account requirements, and return value. It leaves no obvious gaps for an AI agent.

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

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

Schema coverage is 100%, and the description significantly enriches each parameter with clear examples, constraints, and type-specific details (e.g., sec_8k items codes, fred_series series_id).

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 creates a proactive monitoring subscription to a live-data event stream. It specifies the return value (new subscription id) and distinguishes from sibling tools 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 explains when to use the tool (for monitoring events) and details supported types with examples. It also mentions account requirements (Pipeworx OAuth) and constraints on delivery channels. However, it does not explicitly state when not to use or mention alternatives like list_subscriptions.

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 significant context beyond annotations: describes return format (category-bucketed questions with tool+argument shape), sources from live catalog, and explains no-argument vs topic behavior. Consistent with readOnlyHint and openWorldHint.

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 front-loaded query variants. Efficient but somewhat dense; every sentence contributes valuable information.

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

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

Without output schema, description fully explains what the tool returns and the range of topics. Covers all necessary context for an onboarding 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 provides 100% coverage for 1 parameter. Description adds more detail on topic values (e.g., 'finance', 'pharma') and behavior difference when omitted, enhancing 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 is the onboarding entry point for agents, returns category-bucketed example questions, and distinguishes from sibling tools by mentioning it's for getting started and learning meta-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 recommends using this tool first when unsure of Pipeworx's capabilities and to learn meta-tools. Provides guidance on topic parameter to focus. Lacks explicit when-not-to-use, but context is clear.

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

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

Discloses mutability (readOnlyHint false), idempotency (idempotentHint true), non-destructive effect (deactivate not delete), and historical availability via recent_alerts. Adds significant context beyond annotations.

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

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

Two concise sentences: first states action and ownership, second explains behavioral nuance. 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 simple single-param tool, good annotations, and no output schema, description fully covers purpose, precondition (ownership), behavioral effect (deactivation), and cross-tool reference (recent_alerts).

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 'id' with schema description 'Subscription id (uuid) returned by subscribe.' Tool description mentions 'by id' but adds no further detail; schema coverage is 100%, so baseline 3 is appropriate.

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

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

Clear verb-resource pair 'Cancel a subscription by id' and distinguishes from siblings like subscribe and list_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?

States ownership enforcement ('you can only cancel your own subscriptions') and notes deactivation vs deletion, guiding when to use and how history remains. Does not explicitly name 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the dual pipeline (structured SEC EDGAR+XBRL for financial claims, grounded pipeline for others), the verdict types, and citation format. 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?

The description is relatively long but well-structured, front-loading the purpose with example phrases. Every sentence provides useful information. It could be slightly more concise, but it avoids fluff.

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

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

Given the tool's complexity (two distinct verification paths) and lack of output schema, the description comprehensively explains what the tool does, how it routes claims, and what it returns (verdict types, actual value with citation, reasoning). No gaps.

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

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

Input schema coverage is 100% with both parameters described. The description adds value by explaining the tolerance_pct default and use case ('Set 1–2 for hallucination detection'), which goes beyond the schema's description. Does not repeat schema info.

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: verify natural-language factual claims against authoritative sources. It provides explicit example phrases ('fact check', 'verify the claim that...') and specifies the resource (claim verification). It distinguishes itself from sibling tools 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also separates handling for company financial claims vs other claims, giving clear context. It does not provide explicit exclusion statements, but the scope is well-defined.

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

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

Annotations already declare safe, idempotent, non-destructive behavior. Description adds value by stating it validates the number (not product), ignores spaces/dashes, and is offline/keyless—context beyond structured fields. 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?

Three concise sentences, front-loaded with core action, then details. No fluff or repetition. Each 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?

Given one parameter, no output schema, and rich annotations, the description adequately explains what the tool returns (check digit verification, format, normalized GTIN-14, prefix, country). Could explicitly list all return fields for full completeness, but sufficient 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 covers 100% with one parameter, but description adds meaning: input can be from various formats, spaces/dashes ignored, and it normalizes to GTIN-14. This enhances understanding beyond the schema's basic description.

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

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

Description starts with 'Validate a barcode number' and lists specific formats (EAN-13, UPC-A, EAN-8, GTIN-14), making the tool's purpose very clear. It distinguishes from sibling gtin_check_digit by mentioning normalization and country 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?

Implies usage for validating barcodes of specific formats, but does not explicitly state when to use this tool versus the sibling gtin_check_digit or other tools. No when-not or alternative guidance provided.

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