Seo Serp

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

The description adds valuable behavioral context beyond annotations: it discloses that Anthropic requires a BYO key and direct payment, explains the return format (per-model score/confidence/signals/raw_response + combined view), and notes the default model is free. This aligns with readOnlyHint, idempotentHint, and destructiveHint annotations, with 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 at two sentences, front-loading the core functionality and key details. Every sentence adds value: the first explains the main action and output, the second details the default model and optional Anthropic probing. No superfluous text.

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

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

Despite lacking an output schema, the description clearly outlines the return structure (per-model object with score, confidence, signals, raw_response, plus combined view). With 4 parameters (1 required) and full schema coverage, the description provides sufficient completeness for an agent to understand what the tool does and what it returns.

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

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

Although schema coverage is 100%, the description enriches each parameter: for 'entity' it gives concrete examples; for 'models' it lists supported values and default behavior; for '_apiKey' it explains it's only needed when Anthropic is selected and that it's passed directly; for 'context' it provides a usage example. This adds meaning beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It specifies the default model and optional Anthropic probing, and mentions use cases like AI-marketing audits and pre-launch brand checks, effectively distinguishing it from siblings like 'scan_competitor_ai_presence'.

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

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

The description explains when to use the tool (for brand visibility checks, competitive monitoring) and provides usage context (e.g., optional Anthropic key required for certain models). However, it does not explicitly mention alternatives or when not to use it, but the context signals provide sibling tool names that could be 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 read-only, idempotent, open-world, and non-destructive. The description adds valuable context: it routes to a large tool ecosystem, fills arguments, returns citations, works on every tier, and is 'one fast call'. It also notes it can handle live news and breaking-news routing. No contradiction with annotations, and the added behavioral detail is meaningful without being redundant.

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 every sentence serves a purpose: positioning, exclusions, examples, and escalation path. It's front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and organized into readable chunks. While not ultra-brief, the length is justified by the need to differentiate from several siblings and convey 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 the tool's complexity as a meta-router, the description is remarkably complete: it covers scope (6 domains listed), behavior (routing, args, citations), usage triggers, examples, limitations (grounded deep research alternatives), and integration with news. No output schema exists, but the description sufficiently explains what the caller receives. This is fully contextual for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for 'question' and each alias (q, text, input, query, prompt). The description doesn't need to add parameter syntax; it already clarifies natural-language input. Since the schema fully explains the parameters, a baseline of 3 is appropriate; the description's examples reinforce usage but add no new parameter-level semantics.

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

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

The description uses a specific verb ('routes', 'returns') and clearly identifies the resource: ask_pipeworx routes questions to 5,462 tools across 1,419 verified sources and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

Explicitly instructs to prefer over web search for factual questions, states 'START HERE for most questions', and provides clear escalation criteria: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. Includes a list of trigger phrases and concrete examples, which is unambiguous guidance.

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

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

Annotations already declare read-only, idempotent, and open-world hints. The description adds valuable behavioral context: it explains that candidate routing improvements are enabled live when under test, that none is currently active, and that it falls back to nothing—meaning it is a full working router, not a stub. This goes beyond the annotations to disclose the experimental nature and current operational state.

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

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

The description is four sentences and front-loaded with the key identity ('Beta version of ask_pipeworx'). Each sentence adds value: identical behavior, live candidate testing, current no-candidate state, and usage guidance. It is slightly longer than necessary but not bloated.

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

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

Given the tool's complexity (a router with thousands of tools), the description covers the essential context: it is a full working router, identical to ask_pipeworx, with experimental routing. It also notes the same response shape, which compensates for the lack of an output schema. No critical information appears missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents the 'question' parameter and its five aliases. The description does not add extra parameter semantics beyond saying 'same arguments,' but with full schema coverage, the baseline of 3 is appropriate.

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

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

The description explicitly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,462 tools, arguments, and response shape. It distinguishes from the stable router by noting it includes candidate routing improvements, making the purpose clear and specific.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. It also notes that currently no candidate is active, so it matches ask_pipeworx exactly, providing a clear condition for use versus the alternative.

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

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

Annotations already declare safe read-only behavior, but the description adds substantial context: it returns a structured success object with evidence, and explicitly defines refusal reason codes for failure cases. It also discloses the constraint of using ONLY the tool result and the extra LLM call cost, which are not visible in annotations.

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

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

The description is dense but efficiently structured: it opens with the core value proposition, explains the mechanism, lists the exact return shape, provides usage context, and closes with a cost comparison. Every sentence contributes useful information; no filler or redundancy.

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

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

Despite lacking an output schema, the description fully specifies the return object and refusal cases, and explains how this tool differs from the sibling ask_pipeworx. It is sufficiently complete for an agent to select, invoke, and interpret results correctly in high-stakes scenarios.

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

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

Schema coverage is 100%, and the schema thoroughly documents the question parameter and its aliases, so the description need not elaborate. The description adds no additional parameter-level meaning beyond implying the question should be well-formed for high-stakes use. This meets the baseline for high schema coverage but does not elevate it.

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

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

The description precisely states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It goes beyond a simple verb+resource by detailing the process (routing, fetching, extracting from tool result) and explicitly contrasts with the sibling ask_pipeworx, making the unique value 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also gives an alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost tradeoff of one extra LLM call, enabling clear decision-making.

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

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

Despite annotations already indicating readOnly=true and idempotent=true, the description adds extensive behavioral details: market resolution, fan-out examples, response shapes, resolver contract with confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits, illiquid spread warnings, and cancellation rule parsing. This far exceeds typical 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 long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every part adds necessary detail for correct tool usage. While not concise, it earns its length. Minor reduction could improve conciseness.

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

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

Given the tool's complexity (multiple classifiers, fan-out logic, response shapes, error handling), the description covers virtually all aspects. No output schema exists, but response shapes are described in detail. The description is comprehensive and leaves little ambiguity for the agent.

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

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

Schema coverage is 100% and the description adds significant value beyond the schema: it explains acceptable input formats for 'market', provides depth choices with defaults, and clarifies the effect of include_raw. Examples given in the schema and description further enhance understanding.

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 researches Polymarket bets by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes 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 explicit use cases and covers special scenarios like closed markets and low-confidence matches. It gives guidance on when to use but does not explicitly contrast with siblings. However, the detailed fan-out examples and safety checks provide sufficient contextual 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 safe, read-only behavior. Description adds rich details: data sources (SEC EDGAR/XBRL, FAERS, FDA), metrics pulled, off-calendar fiscal year handling, sorting behavior, and output format with citation URIs. 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?

Front-loaded with key usage guidance and examples. Every sentence adds value, but the description is fairly long. Could be slightly more concise while retaining all 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 two entity types, data sources, sorting, output format, and fiscal year handling. No output schema, but description sufficiently explains what is returned. Lacks error handling details, but for a read-only tool, it is fairly complete.

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

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

Schema coverage is 100% with descriptions. The description adds significant meaning by specifying tickers/CIKs for company values, drug names for drug values, and explaining how the data differs per type. This goes beyond the basic 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 clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and includes user query examples, making the tool's purpose instantly recognizable and distinct 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?

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups' and quantifies the benefit (replaces 8–15 lookups). Lacks explicit mention of when not to use, but context implies alternatives like entity_profile.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses substantial behavioral details: returns a findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citations; includes gaps[] for unanswered facets; never invents data; mentions contradictions[] for standard/thorough; explains semantic excerpting; and sets time expectations. 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 every sentence earns its place, covering account requirements, usage scenarios, depth semantics, citation guarantees, and performance. It is front-loaded with the account warning and structured logically, though it could benefit from bullet points for readability.

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

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

With no output schema, the description fully explains return format (findings packet, gaps[], contradictions[], hop field, citation_uri), edge cases (empty gaps for non-catalog topics), performance (15-90s), and tier limitations. The description alone is sufficient for an agent to invoke deep_research correctly.

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

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

Schema already covers both parameters 100%, but the description enriches them significantly: it expands the depth enum with detailed behavior per option ('quick=3 facets... thorough adds a full iterative hop that chases leads + recovers gaps'), and clarifies that the question can be broad/multi-part. This adds value beyond the schema.

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

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

The description opens with a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making its unique role 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?

Provides explicit guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also states the account prerequisite and the fallback if not signed in, leaving no ambiguity about when to use which tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description complements this by specifying that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This adds valuable behavioral context beyond the annotations.

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

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

The description is concise (under 120 words) and front-loaded with the core purpose. It efficiently conveys when to use and what to expect. A slight improvement could be to avoid listing all domains, but it remains clear and structured.

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

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

Given the tool's simplicity (one required parameter, clear annotations, no output schema needed), the description is fully complete. It explains the tool's function, usage context, and output format. No additional information is necessary for an AI agent to correctly select and invoke this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it mentions 'query' briefly but the schema already has detailed descriptions and aliases. No additional parameter semantics are provided.

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 tools by describing the data or task. It lists specific domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes it from other tools by advising to 'Call this FIRST when you have many tools available.' The verb 'discover' combined with the resource 'tools' makes the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist.' It also advises to call this first when many tools are available. While it doesn't explicitly state when not to use it, the context is clear enough for an AI agent to make decisions.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds useful context: parallel fan-out across sources, what each source returns, and soft-fail for patents API.

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 examples and priority guidance. Slightly verbose on return details, but every sentence adds value. Very efficient overall.

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. Given low complexity (2 params, no nested objects) and rich annotations, description 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%, but description enriches semantics: clarifies value accepts ticker or CIK (not names), and type is limited to company. No ambiguity.

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

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

Description clearly states the tool's purpose: full cross-source profile of a US public company in one parallel call. Examples of queries and listed data sources make it unambiguous.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups' and specifies when to use resolve_entity instead. No ambiguity.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description merely says 'Delete' which is consistent but adds no behavioral context beyond what annotations provide. 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?

Two sentences, very concise. The action and usage are front-loaded. Every sentence is essential.

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

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

Given the tool's simplicity (one required param, no output schema), the description and annotations together provide full context for correct usage, including when to use and related tools.

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 parameter description 'Memory key to delete' in the schema. The description does not add additional parameter information, so it meets baseline but provides no extra value.

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 'Delete a previously stored memory by key.' It specifies the action (delete) and the resource (memory by key), and distinguishes from sibling tools by explicitly mentioning '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?

The description provides explicit usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier. Pair with remember and recall.' This tells when to use and suggests related 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?

Description matches annotations (readOnlyHint, idempotentHint, destructiveHint) with 'Fetches the page, extracts...' indicating read-only, idempotent operation. Adds context about output format and site-root placement.

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 succinct sentences plus a bulleted list of use cases. Every sentence adds value, no redundancy. Front-loaded with the core action.

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

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

Despite no output schema, description explains the output as a 'single text blob ready to drop at site-root/llms.txt'. Covers input requirements and optional parameter bounds. Complete for a straightforward 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. The description adds default and max for max_links but does not provide additional semantic detail beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

Description clearly states it generates a production-ready llms.txt file for any URL, with details on fetching, extracting, and emitting markdown format. It distinguishes itself from siblings like scan_competitor_ai_presence and seo_serp_google which serve different purposes.

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

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

Explicitly lists use cases: getting a client's site indexed, drafting llms.txt for own project, auditing competitor AI visibility. However, it does not mention when not to use or alternative tools for related tasks, which could be improved.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds value by specifying returned fields and the effect of the optional parameter, 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?

Two sentences, front-loaded with the core purpose, no extraneous text.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context completely.

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

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

Schema coverage is 100% and description adds no additional parameter information beyond what is in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates return fields, distinguishing it from sibling tools like subscribe 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?

Explicitly advises when to use (review before adding, find ID to cancel), though no exclusions or alternatives are mentioned.

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

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

Annotations are all false, providing no signal, so the description carries the burden. It discloses rate-limiting (5 per identifier per day), that it is free and does not count against quota, and that the team reads digests daily with signal affecting roadmap. These are non-obvious behavioral traits not in the schema. It does not mention the response format, but for a feedback tool this is acceptable.

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

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

Though long, every sentence earns its place. The description is front-loaded with the core purpose, then systematically covers use cases, scope limitation, content guidelines, and behavioral notes. There is no redundancy or filler; the structure leads the reader naturally from what to why to how.

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 purpose, scope, usage conditions, content guidelines, and behavioral expectations, and implicitly indicates the outcome (feedback read daily, affecting roadmap). With a simple 3-parameter schema and no output schema, the description is sufficiently complete for an agent to decide when and how to invoke it correctly.

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

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

Schema coverage is 100%, with detailed descriptions for each parameter (type, context, message). The description adds minor usage nuances (e.g., 1-2 sentences typical, don't paste end-user prompt) but no significant new semantics for the parameters themselves. Since the schema is comprehensive, the description is at the baseline for a well-documented schema.

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

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

The description opens with a clear statement of purpose ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates specific categories (bug, feature/data_gap, praise). This distinguishes it sharply from sibling tools, which are all research or query tools, by defining it as a feedback channel.

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 specifies when to use the tool (for bugs, feature/data_gap, praise) and provides a critical exclusion: ONLY for tools served by this Pipeworx connection, not for other MCP servers. It also advises against pasting end-user prompts, giving concrete guidance on content format.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context: caching (5min-1h), self-aggregating signal, no PII, and derivation from CF analytics-engine. 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?

Three short sentences front-loaded with purpose, followed by use cases and implementation notes. No wasted words.

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

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

Tool has no required params, no output schema, but description adequately explains output (top tools, packs, volume) and caching. Annotations cover safety. Complete for an information retrieval 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 100% of the single parameter with enum and description. Description adds semantic guidance ('Shorter windows surface what's hot now; longer show steady-state demand'), providing value beyond schema.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over a window, with a specific verb and resource. It distinguishes itself from siblings like discover_tools by emphasizing it shows what other AI agents are calling.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning use case) and explains window selection. Lacks explicit when-not-to-use, but use cases are clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, establishing safety. The description extensively discloses behavioral details: monotonicity checks, Jaccard similarity threshold, placeholder filtering, fill check logic, and output structure. No contradictions with annotations.

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

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

The description is lengthy but well-structured: starts with overall purpose, then breaks into modes, followed by semantic anchor, partition filter, fill check, and final note. Every sentence adds value, though some consolidation is possible. It is front-loaded and adequately concise for the complexity.

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

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

Given the tool's complexity (multiple modes, sophisticated checks, fill validation), the description is remarkably thorough. It covers all modes, parameters, output fields, edge cases (placeholders, low similarity), and trading warnings. Without an output schema, it compensates fully by describing the response 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% with parameter descriptions, but the tool's description adds substantial meaning: explains 'event' mode with example slugs, accepts full Polymarket URLs, details 'topic' mode as cross-event scanning, and describes the behavior of each parameter beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three operational modes (no args, event, topic) with specific use cases, making its purpose highly specific and differentiated from sibling tools.

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

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

Provides explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also explains when not to trade (fill check failure) and references polymarket_fill_risk for custom sizing, offering clear usage boundaries.

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

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

Annotations indicate the tool is read-only and idempotent. The description adds extensive detail: caching behavior (1h at KV level), response structure with by_segment and diagnostics, tradeable-edge knobs, and specific model logic (e.g., Kelly fractions, slippage). 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 thorough but overly verbose, containing detailed model math and gating logic that may overwhelm an AI agent. It is well-structured with sections and bullet points, but could be shortened to focus on essential usage 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?

Given the complexity (9 parameters, no output schema, nested response), the description covers all critical aspects: response segmentation, diagnostics, caching, Fed exclusion, and knob effects. It leaves no ambiguity for an AI agent to correctly invoke the tool.

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

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

Schema coverage is 100% with descriptive parameter comments. The description adds value by explaining parameter interactions (e.g., min_partition_leg_kelly applies to per-leg Kelly, not parent) and tradeable-edge knobs, 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 scans Polymarket markets for edges where Pipeworx data disagrees with market price, and distinguishes itself by specifying three model families. It directly addresses the 'what should I bet on today' use case, setting it apart from sibling tools.

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

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

The description explains the tool is for discovering betting opportunities without paging hundreds of markets, and notes Fed bets are excluded due to unreliable data. However, it does not explicitly contrast with siblings like polymarket_arbitrage or polymarket_edge_tracker, though the purpose 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds significant behavioral details: reads from daily snapshots, bounded by 60-day TTL, decay numbers from daily closes not intraday, and conditions for gaps. 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 appropriately sized, front-loaded with purpose, then structured with clear sections (RESPONSE: subfields, LIMITS). Every sentence adds value without redundancy. It is well-organized for an AI agent to parse quickly.

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

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

No output schema exists, so the description fully explains the return structure: tracked[], expired[], snapshot_dates[] with detailed field meanings (trend, decay_pp_per_day, lifespan_days). It also covers limitations (TTL, historical start, settlement gaps), making the output self-explanatory.

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 days and window. The description adds context: 'days (lookback, default 14, max 30)' and 'window (snapshot family, default 1wk)', but slightly understates the min for days (schema says clamp 2-30). Still, it adds meaning beyond the schema by explaining parameters in the edge-persistence context.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It uses a specific verb ('track') and resource ('edge persistence'), and distinguishes from the sibling 'polymarket_edges' by focusing on persistence/decay rather than raw snapshots.

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

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

The description gives clear context: comparing a fresh wide edge versus an old wide edge implies when to use this tool for time-series behavior. It explains output fields (tracked, expired, snapshot_dates) to guide interpretation. However, it does not explicitly state when NOT to use or mention alternatives like 'polymarket_edges' for raw data.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds substantial behavioral context: it explains the tool requires one of `market` or `event`, describes the return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and highlights risks like partial basket fills converting arb to directional positions. This goes beyond the annotations, earning a 4.

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 thorough and well-structured with mode headings (SINGLE-MARKET, BASKET) and explicit warnings. While it is relatively long, the complexity of the tool (two modes, multiple return fields) justifies the length. There is minimal redundancy; every sentence adds value. However, it could be slightly tightened by removing some parenthetical phrases.

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

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

The tool is complex with two modes, four parameters, no output schema, and no nested objects. The description covers all necessary aspects: parameter behavior, return fields, usage context, and risk warnings. It explains critical details like the interpretation of `size_usd` and the risk of forced directional risk. Given the complexity, this description is fully complete.

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

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

Schema description coverage is 100% with all four parameters described. The description adds significant detail beyond the schema: e.g., for `side` it explains 'Basket: default auto — sell if partition sum > 1, buy if < 1'; for `size_usd` it explains 'Single-market: USD to spend (buys) or target proceeds (sells).' It also explains the meaning of return fields. This is excellent parameter documentation.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket) and explicitly differentiates the tool from sibling tools like polymarket_arbitrage and polymarket_edges by advising to use it before those trades.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills convert arb to directional) and implies when not to use it (for smaller trades without arb signals).

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

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

Extensively discloses behavior beyond annotations: compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and the rarity of real spreads. Complements readOnlyHint and openWorldHint 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?

Very dense and informative, but somewhat verbose. Could be slightly tightened without losing meaning. However, front-loaded with core purpose and logically organized into modes and safety fields.

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 complexity (two modes, multiple safety fields, cross-venue comparison), description covers all necessary context: response fields, compatibility conditions, temporal alignment, and skipped counters. No output schema but return values are adequately explained.

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

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

Although schema coverage is 100%, the description adds rich context: lists all topic values, explains override behavior for explicit ticker/slug, and provides examples. Parameter meaning is fully clarified.

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 calculates cross-venue spread between Kalshi and Polymarket, with specific verb 'Cross-venue spread' and resource identification. Distinguishes from sibling tools like polymarket_arbitrage by focusing on venue comparison.

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

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

Explicitly describes two modes (topic and explicit) with tradeoffs, warns that pre-mapped topics often return compatibility_warnings, and explains when spread is not meaningful (non-equivalent bet shapes, unrelated events). No ambiguity about when to use.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds value by explaining scope (identifier-based) and pairing with remember/forget, going beyond the annotations.

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

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

Two sentences, no unnecessary words. Structure is front-loaded with core action, then usage context, then pairing. Every sentence is 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?

For a simple tool with one optional parameter and no output schema, the description fully covers behavior, use cases, and scope. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples of keys but does not provide additional meaning not already present in the schema's parameter description.

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

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

The description clearly states the tool's purpose: retrieve a saved value or list all keys. It uses specific verbs ('retrieve', 'list') and explicitly contrasts with sibling tools 'remember' and 'forget'.

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

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

Description provides explicit usage guidance: use to look up stored context, omit key to list all, scoped to identifier. It also references complementary tools but does not explicitly state when not to use.

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

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

Annotations include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that mark_read:true flags events as read, affecting future calls. This transparency is good, though it slightly contrasts with the idempotentHint by implying state change. No contradiction.

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

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

The description is somewhat long but front-loaded with key information. Every sentence adds value, though minor redundancy exists (e.g., mentioning the alternative endpoint). Still, it remains efficient.

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

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

Given no output schema, the description explains return values (source, citation_uri, payload) and covers all 5 parameters. It also mentions polling and an alternative endpoint, making it fully informative for a read-only 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?

With 100% schema coverage, baseline is 3. The description adds value by explaining the effect of mark_read, the use of 'since' with ISO timestamps, unread_only filtering, and giving an example type 'sec_8k'. This 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 the tool pulls fired events from the subscription feed, specifying the verb 'pull' and the resource 'fired events from your subscription feed'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on recent alerts 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?

The description explains filtering by type and since, and the mark_read functionality. It mentions polling works fine and provides an alternative REST endpoint for scripts/dashboards, offering context for usage. However, it does not explicitly state when not to use this tool.

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

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

Details parallel API calls, fallback from GDELT to GNews, soft-fail for patents, and return structure. 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?

Thorough but efficient; starts with query examples, then explains behavior. Slightly long but well-structured.

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

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

Given complexity and no output schema, description covers return format, parameter details, and fallbacks completely.

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

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

Schema coverage is 100%, but description adds examples and usage tips (e.g., '30d' typical). Adds value 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 clearly states the tool returns a change feed for a company across SEC, news, and patents. Uses query examples and distinguishes from sibling entity_profile.

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

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

Provides explicit usage context (what's new queries) and mentions alternative tool entity_profile. Could be more explicit about when not to use it.

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

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

The description adds behavioral context beyond annotations: scoped by identifier, persistence differences for authenticated vs anonymous sessions. Annotations indicate idempotentHint: true, which the description aligns with. 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 (three sentences), front-loaded with purpose, and uses clear, direct language without redundancy.

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

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

For a simple storage tool with two parameters, the description covers purpose, usage, persistence behavior, and pairing with siblings. It is fully adequate for correct invocation.

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

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

Schema coverage is 100% with descriptive parameter names and examples. The description reinforces the key-value pair concept and gives usage context, adding value beyond the schema.

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

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

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

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

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

The description gives explicit guidance on when to use ('when you discover something worth carrying forward') and mentions pairing with recall and forget. While it doesn't explicitly list when not to use, the context is clear.

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

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

Annotations already disclose read-only/idempotent/non-destructive. Description adds behavioral detail: cascades through multiple endpoints, auto-disambiguation, returns citation URIs. No conflicts 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 moderately long but well-structured with examples and clear type breakdown. Every sentence adds value, though slightly verbose in explanation of outputs.

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 lookup tool with no output schema, the description explains expected returns for both types, citation URIs, and edge case (auto-disambiguation). Missing failure behavior but overall complete enough.

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

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

Schema already covers both parameters fully. Description adds examples, accepted input formats (ticker, CIK, name), and output details per type, enriching parameter understanding. Some redundancy but mostly additive.

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

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

The description explicitly states the tool resolves names to canonical identifiers, provides concrete usage examples ('What's the ticker for...'), and distinguishes it from siblings by positioning it as the first step when an ID is needed. It also details supported entity types and expected outputs, making the purpose unambiguous.

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

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

Gives explicit 'Use FIRST whenever you have a name but need an ID' instruction, and describes when to use for company vs drug. However, it doesn't explicitly state when NOT to use (e.g., 'if you already have an ID, skip this tool'), which could be clearer.

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

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

The description adds behavioral context beyond annotations: it explains that each entity is probed with ai_visibility_check, the returned fields (score, confidence, signal density), and that the context parameter applies to every probe. Annotations already indicate read-only, idempotent, and non-destructive, so the description enriches without contradiction.

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

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

Three sentences with no wasted words. The purpose is front-loaded, followed by the mechanism and an illustrative example. Every sentence earns its place.

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

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

Despite no output schema, the description adequately explains the return value (ranked list with score, confidence, signal density per entity). All parameters are covered, and the behavior is fully described for a complex tool. Nothing essential is missing.

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

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

All 4 parameters are described in the schema (100% coverage). The description adds further meaning: 'First entry treated as the subject for narrative' for entities, and clarifies that context disambiguates common names. This goes 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 the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use or mention alternative tools, leaving a gap for agents to decide.

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

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

The description adds behavioral context beyond annotations: explains partial failure handling, timeout behavior for bundlephobia (5-30s first measurement), and the composite nature. 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 concise (3-4 sentences) yet information-dense, front-loading purpose and usage, then adding important behavioral details. Every sentence serves a purpose without redundancy.

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

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

Despite no output schema, the description fully enumerates the return fields (summary block, per-advisory detail, links, alternative versions) and describes error handling, making the tool's output fully predictable for an agent.

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

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

With 100% schema coverage, the description still adds value by noting scoped packages are accepted for 'package' and defaulting to latest version for 'version'. This clarifies usage beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, covering license, advisories, version history, and bundle size. It explicitly distinguishes from siblings by noting NPM-only scope and mentioning alternative tools for other ecosystems.

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

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

The description provides explicit usage scenarios ('is X safe / popular / small') and clearly states when not to use ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), effectively guiding the agent to the correct tool.

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

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

Discloses beyond annotations: embedding model (BGE-base-en), cosine similarity, 500-char windows, 200K char cap with truncation flag, and offset verification. 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?

Concise 4-sentence paragraph front-loading purpose, then usage, pairing, and technical details. 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?

Covers all needed aspects: purpose, when to use, output details (passages with offsets and scores), pairing with sibling, and technical constraints. Complete for moderate complexity.

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

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

Schema coverage is 100% (baseline 3). Description adds examples for query, clarifies text cap and limit range, enhancing understanding beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific examples like SEC 10-K body or article, and differentiates it from sibling tools 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?

Explicitly states when to use (when record is too big for prompt) and pairs with ask_pipeworx_grounded, providing clear alternatives and 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 indicate readOnlyHint, idempotentHint, and destructiveHint are false. The description adds value by specifying it returns live results, and names the returned 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?

Extremely concise: one sentence plus an example. Every word serves a purpose, and the example is instructive. No wasted 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 that all parameters are documented in the schema and annotations cover behavioral traits, the description is complete enough. It mentions the key output fields, which is sufficient since there is no output schema. Could optionally include more detail on return structure, but not necessary.

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 every parameter is already explained. The description reinforces with an example but adds minimal additional meaning beyond the schema. Baseline score 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?

Description clearly states the tool returns live organic search results for a keyword on Google, listing specific fields (rank, title, domain, URL, snippet). This distinguishes it from sibling tools like deep_research or compare_entities, which have different purposes.

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

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

Explicitly says it's for SEO rank-tracking and SERP analysis, and provides an example usage. However, it does not explicitly state when to use this tool versus alternatives, though the purpose is clear enough.

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

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

Adds behavioral context beyond annotations: returns subscription ID, webhook secret returned once, auto-disabled after 10 consecutive failures, OAuth requirement. Annotations already indicate non-readOnly, idempotent, non-destructive. Description aligns and enriches 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?

Packed with information but somewhat dense; each sentence is necessary. Could benefit from bullet points for readability, but not overly verbose. 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?

Covers all essential aspects for a complex tool: OAuth requirement, type-specific filters, delivery options with constraints, return value. No output schema, but return value is mentioned. Complete guidance for an agent to use correctly.

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

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

100% schema coverage provides baseline; description adds significant value by explaining each type's parameters (e.g., items codes for sec_8k, topic for polymarket_edge, conditions for clinical_trial) and delivery object properties with verification and rate limits, far exceeding schema descriptions.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verb and resource. Distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by describing subscription creation and its persistent nature.

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

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

Explicitly states requirement of Pipeworx OAuth account (anonymous/BYO cannot persist), lists supported subscription types with parameter examples, and provides delivery channel constraints (verified phone, SMS cap, webhook signing). Offers clear when-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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it is a 'getting started' tool that returns example questions with tool shapes, and that calling with no arguments gives full spread. 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 well-structured with front-loaded example queries, followed by purpose and parameter details. Every sentence adds value: first line lists typical user queries, second explains what it returns, third gives parameter usage. No redundancy or filler.

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

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

Given the simple input schema (1 optional param, no output schema), the description fully covers the tool's purpose, behavior, and when to use it. It explains the response format (category-bucketed examples) and provides guidance on parameter usage, making it complete 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 description coverage is 100% for the single parameter 'topic'. The description adds value by providing concrete example values ('finance', 'pharma', 'betting') and explaining that omitting topic gives a cross-category spread. This supplements the schema's generic description.

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

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

The description explicitly states the tool's purpose: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the verb 'returns category-bucketed example questions' and the resource 'tools+argument shapes'. This clearly distinguishes it from siblings like ask_pipeworx or discover_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 provides clear usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It implies when to use and mentions alternatives like ask_pipeworx, entity_profile, compare_entities as things to learn. However, it does not explicitly state when not to use it.

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

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

The description adds behavioral context beyond annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events. 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?

Two sentences, front-loaded with the action (Cancel by id), 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?

Complete for a simple tool; explains effect on row and ownership policy. No output schema needed.

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 does not add significant meaning beyond the schema's parameter description.

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

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

The description clearly states the action ('Cancel') and the resource ('subscription'), and distinguishes it from sibling tools 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?

The description includes ownership enforcement ('you can only cancel your own subscriptions') and explains the effect on the row, but does not explicitly state when to use vs. alternatives. The use case is clear for a single-purpose tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: the two-tier processing (fast path for financial claims, grounded pipeline for others), the verdict types, citation format, and reasoning output. 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 information-dense and well-structured, starting with clear examples and purpose, then detailing the two verification paths. While slightly verbose (multiple lines of examples), every sentence adds value. Could be slightly more concise by removing redundant phrases.

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

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

Given the absence of an output schema, the description thoroughly explains the return values (verdict, actual value with citation, reasoning). Both parameters are fully described, and the tool's complexity is well-addressed. No gaps remain for an agent to make incorrect assumptions.

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

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

Schema coverage is 100% with both parameters described. The description adds that tolerance_pct overrides the claim's implied tolerance and is capped at 5% by default, and provides concrete examples for the claim parameter. This adds significant meaning beyond the schema.

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

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

The description uses clear natural-language examples like 'Is it true that...' and 'fact check', establishing a precise verb-resource relationship. It distinguishes itself from sibling tools by noting it replaces 4-6 sequential calls and covers both financial and general claims, which no sibling explicitly does.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims and other claims with different verification paths. However, it does not mention when not to use it or list specific alternatives among siblings.

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