Diffbot

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return structure (per-model {score, confidence, signals, raw_response} + combined view) and the payment implication for Anthropic calls, going beyond what annotations provide.

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

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

The description is two sentences, front-loads the core purpose and default behavior, and includes essential details without redundancy. Every sentence earns its place, making it easy to parse.

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 adequately summarizes return fields. It covers parameters, default model, optional key, and use cases. However, it lacks details on how confidence is computed or what 'signals' entail, leaving minor gaps for a complete understanding.

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

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

Schema coverage is 100%, but description enriches understanding by explaining the default model, optional nature of 'models' array, and that '_apiKey' is only needed for Anthropic. It clarifies that 'context' helps disambiguate names, adding practical meaning 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?

The description clearly states the verb (probe) and resource (LLMs for visibility scores), and distinguishes from sibling tools like 'deep_research' or 'scan_competitor_ai_presence' by focusing on per-model visibility scoring. It specifies the default model and optional Anthropic integration.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), but does not mention when to avoid using it or directly compare with siblings. The guidance on model selection (default vs. BYO key) is helpful.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds valuable behavioral context: routes to 5,529 tools across 1,455 sources, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is one fast call. 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?

Despite being long, every sentence serves a distinct purpose: recommending over web search, listing supported domains, explaining routing behavior, giving usage triggers, providing examples, and naming escalation alternatives. It is front-loaded with 'PREFER OVER WEB SEARCH' and structured as a single coherent flow.

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 broad, high-complexity tool with no output schema, the description is complete: it explains what it does, when to use it, what it returns (structured answers with citations), how it interacts with sibling tools, and even covers niche cases like live news requests. 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?

Input schema coverage is 100% with aliases documented, so baseline is 3. The description adds examples of appropriate questions ('current US unemployment rate', 'Apple's latest 10-K'), which give concrete semantic guidance beyond the schema's generic 'natural language' description. This pushes it to 4.

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

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

The description clearly states the tool answers factual questions by routing to authoritative sources, and explicitly distinguishes it from siblings: 'PREFER OVER WEB SEARCH', 'START HERE', and contrasts with ask_pipeworx_grounded and deep_research. The verb 'ask' and resource 'Pipeworx' are specific and 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?

Extensive when-to-use guidance is provided: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and explicit escalation paths: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also notes news routing for 'what's the world saying'.

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 meaningful behavioral context beyond the annotations: it explains the experimental edge, that routing candidates are tested live, that currently no candidate is active so it matches ask_pipeworx exactly, and that results are compared against the stable router. It also clarifies that it is a full working router. These details go beyond the readOnly/idempotent hints and enrich the agent's understanding of the tool's behavior.

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

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

The description is front-loaded with the core identity and differentiation ('Beta version of ask_pipeworx: identical universal router...'). It is moderately long but each sentence earns its place, covering beta status, current state, usage guidance, and a clarification that it is a full router. No filler or repetition is present.

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, combined with the annotations, provides a solid understanding of the tool: what it does, its experimental nature, current state, and when to use it. Since there is no output schema, it references 'same response shape' as ask_pipeworx, which is a known sibling and provides a point of reference. It is sufficiently complete for an AI 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?

The input schema fully documents the required 'question' parameter and its aliases (q, text, input, query, prompt) with a coverage of 100%. The description does not add any parameter-specific guidance beyond noting 'same arguments' as ask_pipeworx, which refers to the underlying tools, not the input schema. Since the schema is complete, the baseline score of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx: an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling by highlighting the experimental routing improvements. The resource and action ('ask' with a question) are specific and 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 explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router, providing clear when-to-use context. It also clarifies that it is a full working router, not a fallback. It does not explicitly list when not to use it, but that is strongly implied by the comparison to the stable version.

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

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

Beyond the annotations (read-only, idempotent), the description reveals the tool's refusal behavior with specific refusal_reason enums, the fact it only uses tool result content, the return schema including verbatim evidence, and the one extra LLM call cost. 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 each section serves a purpose: definition, routing explanation, return shape, refusal reasons, use cases, and cost trade-off. It is front-loaded with the core purpose and avoids fluff.

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

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

There is no output schema, so the description provides both the success return fields and the refusal reason enums. It covers routing behavior, use cases, and cost trade-off, making it fully adequate for an agent to decide and invoke correctly without needing further context.

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

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

The input schema already fully describes the question parameter and all 5 aliases (100% coverage). The description adds context about how the question will be used (routing and extraction), but doesn't need to compensate for schema gaps, so a baseline 3 is appropriate.

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

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

The description opens with a clear purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly distinguishes from sibling ask_pipeworx by describing the grounding behavior and return of evidence/refusals, making the tool's function specific and recognizable.

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

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

Explicit guidance is given: use for answers that will be 'quoted, cited, or acted on' and must not invent facts, while preferring ask_pipeworx for casual lookups. It also notes the extra LLM call cost, further clarifying when to choose this over alternatives.

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

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

Annotations already declare readOnlyHint=true, but the description goes far beyond by detailing resolution logic, fan-out, safety short-circuits, closed market handling, spread warnings, and resolution-rule risk. 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 very long but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety). Could be more concise; some details could be moved to documentation.

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 of Polymarket betting research, the description comprehensively covers input, output, edge cases, safety, and response shapes. Despite no output schema, it explains the structure of results and provides examples. Very 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?

Input schema covers 100% of parameters with descriptions. The description adds meaningful context: explains the 'depth' enum (quick vs thorough), when to use 'include_raw', and provides examples for 'market'. 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 clearly states the tool researches a Polymarket bet by pulling Pipeworx data, and specifies input types (slug, URL, question text). It also lists classifiers and fan-out examples, distinguishing it from siblings like polymarket_arbitrage or polymarket_edges by being a comprehensive research tool.

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

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

It explicitly tells when to use ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), but does not provide explicit when-not-to-use or alternative tool recommendations. However, it gives detailed guidance on interpreting results and handling edge cases.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds significant behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, result sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

The description is somewhat long but front-loaded with example queries. Every sentence adds useful information, and it avoids redundancy. Minor improvement could be better structuring with bullet points, but it's 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?

Given no output schema, the description explains return structure (paired data + citation URIs). It covers both entity types and mentions result ordering. The tool has only 2 simple parameters, and the description provides all necessary context for an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the meaning of each type value (company vs. drug) and the format for values (tickers/CIKs for companies, names for drugs). It also clarifies constraints like max 5 items. This goes beyond the schema's brief 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 performs side-by-side comparison of 2-5 companies or drugs in a single call. It uses specific verbs like 'compare' and identifies the resources (companies/drugs). It distinguishes from sequential single-pack lookups, which are implied as alternatives.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives example queries that should trigger this tool, making it easy for the agent to decide when to use it over siblings 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?

Annotations already declare readOnly, openWorld, and idempotent hints, but the description goes far beyond by disclosing account requirements, paid tier restrictions, expected latency (15-60s, up to 90s), the gaps[] behavior (never invents), contradictions[], the hop field, citation_uri fetchability, and semantic excerpting of large records. This is rich behavioral context.

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

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

The description is long but every sentence contributes operational value—account prerequisites, timing, sibling alternatives, depth semantics, citation guarantees, and gap handling. It is structured and front-loaded with the account requirement first, but it could be tightened slightly for easier scanning.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it explains the findings packet format, gaps[], contradictions[], citation_uri behavior, hop semantics, latency, prerequisites, and not-invented guarantee. An agent could select and invoke this tool appropriately with full understanding of consequences.

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 at 100%, so baseline is 3, but the description adds substantial meaning beyond the schema: it explains that depth controls the number of facets (quick=3, standard=5, thorough=8) and describes the research behavior for each, including gap recovery and contradiction scanning. This goes well beyond the schema's enum 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 identifies the tool as grounded multi-source research across Pipeworx's 1455 structured data sources in a single call, using the specific verb 'research' and explicit resource. It distinguishes itself from ask_pipeworx and open-web search, so the purpose is unambiguous and well differentiated 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?

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly directs users to ask_pipeworx for single lookups, breaking/current-news topics, and when not signed in. Also details the meaning of depth levels, giving clear selection criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, indicating safe, non-destructive, idempotent reads. The description adds behavioral context by listing the exact return fields (e.g., description, homepage, employee count), providing transparency beyond the schema. No contradictions.

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

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

The description is two concise sentences plus a code example, front-loading the main purpose and return values. Every sentence adds value, and the example demonstrates usage. No unnecessary words or repetition.

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

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

Despite no output schema, the description lists all expected return fields (description, homepage, employee count, revenue, industries, etc.), which is critical for an agent. Parameters are fully documented via schema, and the purpose is clear. The tool is well-specified for its complexity.

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

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

Schema description coverage is 100% with descriptions for all three parameters. The description adds little beyond the schema: it reiterates the use of 'name' and '_apiKey', and mentions the optional URL for disambiguation, but the schema already covers these details. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: looking up company details from the Diffbot Knowledge Graph. It lists specific return fields (employees, revenue, industry, etc.) and provides an example, making it easy to understand. Among siblings, it is distinct from general extraction tools like 'diffbot_extract' or '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?

The description implies usage for enriching a company by name or URL, with an example. It does not explicitly state when to use versus siblings or provide exclusions, but the purpose is clear enough for an agent to decide. Lacking explicit when-not or alternative tool references.

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 states it extracts and returns structured data, which aligns with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations. However, it adds no additional behavioral context beyond what annotations already provide, such as API rate limits or authentication details.

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

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

Two sentences front-load the primary action ('Extract the structured content...') followed by an example. No superfluous words; every sentence adds value.

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

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

Given the low complexity (2 parameters, no output schema) and strong annotations, the description is largely sufficient. It lists return fields and provides an example. Minor gap: no explanation of the return format, but it's reasonable for a simple extraction tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description includes an example but does not add new semantic information 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 explicitly states the verb 'extract' and the resource 'structured content from a URL', listing specific fields returned. It clearly distinguishes from sibling tools like diffbot_company, which focuses on company data.

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

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

The description implies usage for extracting content from web pages but provides no explicit guidance on when to use this tool versus alternatives like diffbot_company or search_within. No exclusions or prerequisites 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 already indicate read-only, non-destructive, idempotent behavior. The description adds value by explaining that results include full input schemas with curated examples and are ready to call directly, which supplements the lack of an output schema.

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

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

The description is dense and front-loaded with purpose. It uses active voice and lists examples efficiently. Minor improvement could be structuring into bullet points, but it remains concise.

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

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

Despite no output schema, the description fully explains the return value: names, descriptions, full schemas with examples, ready to call. This is complete for a discovery tool given its moderate complexity.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description adds aliases (task, q, description, search) and provides example queries, enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool finds tools by describing data or task, lists specific domains (SEC filings, financials, etc.), and explains it returns top-N tools with schemas. It distinguishes itself from siblings by saying 'Call this FIRST' for option discovery.

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

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

The description explicitly says when to use: 'when you need to browse, search, look up, or discover what tools exist' and advises calling it first. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds beyond: explains fan-out across sources, specifics of each returned component, notes patent data soft-fails due to USPTO sunset, and fallback behavior (GDELT→GNews). No contradiction.

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

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

Single paragraph but dense with information. Each sentence contributes value: example queries, output components, limitations. Could be slightly more structured but remains 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?

No output schema exists, yet description fully explains returns: cik, company_name, recent_filings with URIs, fundamentals with sort order, patents, news, LEI. Also mentions limitations and fallback. Complete for a holistic profile 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 descriptions for both parameters. Description adds context: type only 'company', value can be ticker or zero-padded CIK, and explicitly states names not supported. This clarifies usage beyond schema.

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

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

Description explicitly states the tool's purpose: 'full cross-source profile of a US public company' with example queries like 'tell me about X', 'research Acme', etc. Clearly distinguishes from sibling tools like resolve_entity.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises to use resolve_entity if only a name is available, setting clear when-to-use and 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 already declare destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data and pairing with other tools, but does not provide additional behavioral details beyond deletion.

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, no redundant information. 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?

With a single parameter, no output schema, and annotations covering destructive nature, the description provides complete context: what it does, 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 clear description 'Memory key to delete'. The description adds little beyond the schema, only mentioning 'by key' and 'previously stored memory', which is minimal enhancement.

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' with a specific verb and resource. It distinguishes itself from sibling tools by referencing 'remember' and 'recall', making it clear that this tool is for deletion.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with remember and recall, providing clear context and alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral details: fetches the page, extracts title/description/key links, and emits standard markdown format. No contradictions.

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

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

Two concise sentences plus a bullet list of use cases. Every sentence adds value, no wasted words. Front-loaded with the core action and audience.

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 explains the output format and practical usage. Covers tool scope, method, and typical scenarios adequately for a simple tool with two parameters.

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 schema already describes both parameters. The description does not add additional meaning beyond what's in the schema, earning baseline score.

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

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

The description clearly states the verb 'generate' and the resource 'llms.txt file', and specifies the context 'for any URL'. It distinguishes itself from sibling tools by focusing on a specific output format and use cases like indexing or auditing.

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 lists explicit use cases (getting a client's site indexed, drafting for own project, auditing a competitor), but does not mention when NOT to use or name alternative tools. However, given siblings, no direct alternative exists.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds the returned fields and implies default behavior (active only). No contradictions.

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

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

Two sentences, no fluff. Information is front-loaded and 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?

For a simple list tool with one optional parameter and no output schema, the description covers return structure, usage guidance, and default behavior. Fully adequate.

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

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

Schema coverage is 100% with one described parameter. Description adds context by implying default active subscriptions, complementing the schema without repetition.

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 specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from siblings 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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides 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?

Despite annotations being all false, the description discloses rate limits ('Rate-limited to 5 per identifier per day'), the claim_token flow for later status checks, and that it is 'Free; doesn't count against your tool-call quota.' This exceeds what annotations convey.

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

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

The description is dense with every sentence contributing useful information—purpose, use cases, exclusions, claim_token mechanics, and rate limits. It is slightly longer than minimal but well-organized and front-loaded with the core purpose.

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

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

With no output schema, the description explains return behavior ('Filing without an account returns a claim_token') and how to later retrieve resolution status. It also mentions team reading cadence, making it complete for a feedback 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 descriptions already cover all 4 parameters (100% coverage), giving the description a baseline of 3. It adds the standalone claim_token usage pattern and instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' enriching parameter 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb+resource pairing. It distinguishes from siblings by scoping to 'tools served by this Pipeworx connection' and contrasting with other MCP servers.

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 conditions: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives a clear exclusion: 'if the tool came from a different MCP server ... file it with that server instead.'

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and the self-aggregating nature. This adds significant behavioral insight.

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

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

The description is concise, structured with a clear main sentence, bulleted use cases, and supplementary details. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage context, behavioral details, and parameter semantics. It is complete and leaves no significant gaps.

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

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

Schema coverage is 100% and the description adds meaning: it explains the effect of different windows (short vs long) and provides guidance on choosing between them. This goes beyond the schema's enum list.

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 configurable windows, with three explicit use cases. It differentiates from siblings by focusing on trending analytics rather than direct querying or entity resolution.

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 three specific scenarios where the tool is useful (discovering hot data, confirming canonical tools, aligning use cases). It lacks explicit "when not to use" or alternative tool mentions, but the context is sufficiently clear for an agent 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?

Annotations indicate safe read-only operation. Description adds extensive behavioral details: monotonicity checks, partition-sum checks, semantic anchor (Jaccard similarity), partition filter (placeholder drops), fill check against CLOB depth. No contradictions with annotations.

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

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

Description is detailed but well-structured, with main modes upfront and supporting details following. While lengthy, every sentence adds necessary context for a complex tool. Slight verbosity in technical explanations keeps it comprehensive.

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, filtering heuristics, fill check) and absence of output schema, the description thoroughly explains inputs, logic, response fields, and edge cases. It is complete for effective agent usage.

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

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

Schema coverage is 100% (both parameters described). Description adds meaning beyond schema: explains event slug vs topic seed question, and how each mode works (e.g., child markets, date-axis ordering).

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

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

The description uses specific verbs ('Find arbitrage opportunities') and identifies the resource (Polymarket). It clearly distinguishes between three usage modes (no-args, event, topic) and references a sibling tool (polymarket_fill_risk) for custom sizing, aiding selection.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. Also provides fill-check criteria to avoid trading when edge is not realizable, and directs to polymarket_fill_risk for custom sizing.

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

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

The description discloses extensive behavioral traits beyond annotations: response structure with three segments, caching at 1h, fed candidates exclusion, diagnostics for empty segments, and per-opportunity fields. Annotations (readOnlyHint, idempotentHint) are consistent and not contradicted.

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 verbose (~500 words). While it front-loads purpose, the detailed model family explanations and filter logic could be condensed. Every sentence is informative but conciseness is sacrificed for completeness.

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 9 parameters, no output schema, the description fully explains the return structure (by_segment, fields per opportunity, diagnostics) and all relevant behaviors (caching, knobs, filter skips). It leaves minimal ambiguity for an agent.

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

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

Schema coverage is 100% with good descriptions. The tool description adds incremental value, e.g., explaining slippage_pp context (zero fees but bid/ask typical 20-50bp) and min_partition_leg_kelly behavior. This lifts it above the baseline of 3.

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

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

The description states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' with a specific verb and resource. It differentiates from siblings like polymarket_arbitrage by focusing on edge discovery from model disagreement, not pure arbitrage.

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 targets 'what should I bet on today' and mentions discovering opportunities without paging. However, it does not explicitly list when not to use it or compare directly with siblings. The context and purpose make usage 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 safety (readOnly, idempotent, non-destructive). The description adds significant behavioral details: response structure, decay computation method, snapshot gaps, and that history depth is bounded by 60-day TTL. 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 sections, but slightly verbose. It effectively front-loads the key question. A minor reduction in length could improve conciseness without losing clarity.

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

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

Given the lack of an output schema, the description thoroughly documents the response structure (tracked, expired, snapshot_dates) and explains computed fields. It covers all behavioral aspects needed for correct usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds default values (14 for days, '1wk' for window), valid range for days (2-30), and clarifies 'window' as snapshot family. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool's core purpose: analyzing edge persistence and decay over time. It uses specific verbs ('answers', 'tracks') and distinguishes from sibling 'polymarket_edges' by focusing on time-series analysis rather than current edges.

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

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

The description provides contextual guidance (e.g., a fresh wide edge vs 3-week-old wide edge are different) and explains limitations (snapshot TTL, gaps). However, it lacks explicit 'when not to use' or alternative tool recommendations.

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, destructiveHint=false, etc. The description adds detailed behavioral context such as walking the order book ladder, returning verdict (clean|degraded|cannot_fill), and naming forced directional risk legs. 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 relatively long but well-structured with bold headings for modes. Every sentence adds value, though some minor redundancy could be trimmed. Front-loaded with the core purpose.

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

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

Despite no output schema, the description thoroughly explains return fields for both modes. It covers all parameters, default behaviors, edge cases (thin legs, forced directional risk), and provides actionable verdicts. Complex tool fully contextualized.

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 documented. The description adds considerable value beyond the schema by explaining mode-specific behavior, default values, interpretation of size_usd for buys vs sells, and auto side logic for baskets.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by providing usage context.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains when to use each mode and warns about partial basket fills converting arb into unhedged directional risk.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are present and the description adds rich behavioral context: explanation of safety fields (compatibility_warning, temporal_alignment, skipped counters), the fact that spreads may be meaningless under certain conditions, and that pre-mapped shortcuts often return warnings. 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 appropriately sized for a complex tool. It front-loads the core purpose and mode explanation, then details response fields and safety indicators. While comprehensive, it could be slightly more structured with bullet points or clearer separation of sections. However, every sentence earns its place.

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

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

Given the tool's complexity (no output schema), the description provides complete information: it explains all response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and the conditions under which spreads are meaningful. The agent has sufficient context to interpret results without needing external documentation.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it lists all 10 topic shortcuts with explicit values, gives examples for explicit tickers, explains that explicit parameters override topic-mapped sides, and describes the response structure. This fully compensates for any brevity in 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. The two modes (topic shortcuts and explicit tickers) are explicitly described.

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

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

The description provides explicit guidance on when to use (comparing prices across venues) and when not to (when compatibility_warning fires due to non-equivalent bet shapes, semantically unrelated events, or temporal misalignment). It also sets expectations that most pre-mapped topics are not tradeable, helping the agent avoid false positives.

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. The description adds valuable context about scoping to the agent's identifier and the behavior when the key is omitted. 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 two sentences that are front-loaded with the main purpose. Every sentence adds value, and there is no unnecessary text.

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

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

Given the tool's simplicity and the fact that there is no output schema, the description adequately covers usage, scope, and behavior. It could mention the return format but is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% (1 parameter). The description adds meaning beyond the schema by explaining that omitting the key lists all saved keys, and provides examples of typical values like 'user_research_topic'.

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

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

The description clearly states the tool retrieves a value previously saved via 'remember' or lists all keys when the argument is omitted. It distinguishes itself from sibling tools 'remember' and 'forget' by focusing on 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 explicitly says when to use the tool: to look up stored context like a user's target ticker or prior research notes. It also mentions pairing with 'remember' and 'forget'. However, it does not explicitly state when not to use it or mention alternative tools.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds behavioral context: the mark_read parameter modifies read state, and the tool returns the same data as a REST endpoint. It does not contradict annotations and adds useful details.

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

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

The description is a single paragraph of 4 sentences with no wasted words. It front-loads the main action and quickly covers parameters, usage, and alternatives. Every sentence earns its place.

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

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

Given no output schema, the description adequately describes return values (source, citation_uri, raw payload). It covers all 5 parameters, provides usage examples, and mentions an alternative access method. The tool is simple and the 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%, so baseline is 3. The description adds semantic value beyond the schema: it explains that mark_read flags events as read so the next call shows only newer ones, and it mentions the default limit of 50. This helps the agent understand parameter behavior.

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

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

The description opens with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It specifies the return fields (source, citation_uri, raw payload) and filtering options, distinguishing it from sibling tools like `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 provides clear context: it explains filtering by type and since, and the mark_read behavior. It mentions polling works and points to an alternative REST endpoint. However, it does not explicitly state when not to use this tool or compare it to other sibling tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, etc. Description adds significant behavioral detail: fans out to multiple sources, fallback from GDELT to GNews on rate limits/5xx, USPTO soft-fail, parallel call efficiency, return format with citation URIs.

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

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

Single concise paragraph packed with all essential information. Every sentence adds value: examples, sources, fallback, return structure, and alternative tool reference. Front-loaded with user-friendly query examples.

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

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

Despite no output schema, description explains return format (changes[] grouped by source, total_changes, citation URIs). Covers all sources, fallbacks, parameter details, and sibling differentiation. No gaps for a tool of this complexity.

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

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

Input schema covers all 3 parameters with descriptions (100% coverage). Description adds valuable context: for 'since' gives examples like '2026-04-01', '7d', '1y' and suggests '30d' for monitoring; for 'value' mentions ticker or CIK; for 'type' confirms only 'company'.

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

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

Description starts with example queries ('What's new with X', 'latest on Y'), specifies exactly what it does: change feed for a company fetching filings, news, and patents in a single call. It clearly distinguishes from the sibling tool entity_profile by stating 'use entity_profile instead when you want the static 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 example queries and explains when to use this tool vs entity_profile. Includes relative time formats ('7d', '30d') and fallback logic (GDELT→GNews). Gives typical monitoring recommendation ('30d' or '1m').

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

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

Adds significant behavioral context beyond annotations: scoping by identifier, persistence differences for authenticated vs anonymous (24 hours). Annotations already indicate idempotent and non-destructive, but description enriches understanding.

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

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

Single focused paragraph, every sentence provides value, no redundancy. Front-loaded with core purpose.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, behavioral details, and pairing with siblings. Fully adequate for agent understanding.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description provides examples (e.g., 'subject_property') but does not add new meaning beyond the schema.

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

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

Clearly states the verb 'Save' and resource 'data', specifies reuse across conversations/sessions, and distinguishes from sibling tools recall and forget by mentioning them explicitly.

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

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

Explicitly describes when to use: 'when you discover something worth carrying forward' with concrete examples. Does not provide when-not scenarios, but context is clear given sibling differentiation.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds rich behavioral context: identifiers are source-labelled, unresolved identifiers appear under an explicit 'unresolved' field, and LEI/FIGI enrichment degrades gracefully if upstream sources are unavailable. No contradiction with annotations.

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

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

The description is lengthy but well-structured, front-loading with examples, then purpose, then detailed type breakdowns. Every sentence delivers useful information, though some trimming could improve conciseness without losing value. Organizes complex information logically.

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 compensates thoroughly by explaining return behavior: source-labelled identifiers, explicit 'unresolved' field, graceful fallback for GLEIF/OpenFIGI, and citation for drug lookups. It covers edge cases like service unavailability and internal cascading, making it self-sufficient for an agent.

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

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

Despite 100% schema coverage, the description significantly enriches parameter understanding. It details what each 'type' returns (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand) and enumerates acceptable values for 'value' (ticker, CIK, name; brand/generic). This goes well beyond the schema's minimal 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 explicitly states the tool 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input,' with a specific verb and resource. It lists numerous example queries and supported entity types (company, drug), and it distinguishes itself from siblings by positioning as the prerequisite lookup tool.

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

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

Provides explicit directive: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to use the tool. It also mentions that it 'replaces 2-3 manual lookups,' implying efficiency and suitability for multi-step lookup scenarios.

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

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

Annotations already indicate the tool is read-only and idempotent. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized, providing transparency beyond annotations.

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

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

The description is two sentences, front-loaded with the core purpose. The second sentence adds the use case and return value, with no extraneous information. Every sentence earns its place.

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

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

Given the complexity (4 parameters, no output schema), the description covers the tool's behavior, internal steps, return value (ranked list with score, confidence, signal density), and a concrete example. It is fully informative.

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

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

The schema has 100% description coverage, so baseline is 3. The description adds semantic value by specifying that the first entity is treated as the 'subject' for narrative and the rest as competitors, which is not in the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb and resource. It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (likely more general) by emphasizing the competitive audit use case.

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 clear use case (competitive AI-marketing audits) and an example question. However, it does not explicitly state when not to use the tool or mention alternative tools for single-entity checks, though the context of comparing multiple entities is implicit.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint (all safe). Description adds valuable behavioral context: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' No contradiction with annotations.

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

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

Well-structured: starts with core purpose, then usage guidance, ecosystem limitations, failure behavior. Every sentence adds value. Slightly long but not wasteful; could be slightly more concise without losing clarity.

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

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

Despite lacking an output schema, the description thoroughly lists all return fields (summary block, per-advisory detail, links, alternative versions). It covers failure modes and timing. For a 2-parameter tool with 100% schema coverage and full annotations, this 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% for both parameters, so baseline is 3. Description adds meaning beyond schema: explains that 'version' defaults to latest when omitted, accepts scoped packages. Also describes the return fields in detail, compensating for lack of output schema. This extra context justifies a 4.

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

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

The description clearly states a specific verb+resource: composite check for npm package safety/size/popularity. It distinguishes from siblings (none are npm-specific) and describes the integrated services (deps.dev, bundlephobia).

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

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

Explicitly states when to use: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also provides exclusions: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.' This gives clear alternatives.

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

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

Beyond annotations (readOnly, idempotent, etc.), description details embedding model, window size, 200K char cap with truncation, and output properties (offsets, similarity scores). 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?

Information-dense and front-loaded with key action. Slightly long but every sentence adds value; could be trimmed slightly without loss.

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

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

Given no output schema, the description explains return format (passages with offsets and scores) and limitations (cap, truncation), making it fully actionable.

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 good descriptions. The tool description reinforces the purpose but does not add significant extra semantics beyond what is in the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verbs and resource. Examples (SEC 10-K, article) and pairing with sibling ask_pipeworx_grounded differentiate it from other tools.

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

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

Explicitly advises use when record is too large for prompt, saving context. Implicitly limits use to fetched records. Does not explicitly state alternatives for small records, but guidance 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?

The description reveals important behavioral details beyond annotations, such as the idempotent nature (implied by 'new subscription id' but not contradicting idempotentHint), delivery channel limitations (SMS cap, webhook auto-disable after 10 failures), and that the webhook secret is returned only once. This significantly supplements the annotation hints.

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

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

The description is well-structured with a clear front-loaded purpose, followed by prerequisites, type examples, and delivery details. While comprehensive, it is slightly lengthy but every sentence adds value. Minor conciseness improvement possible.

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

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

Given no output schema, the description adequately explains that the tool returns a subscription id and details the webhook secret. It covers all parameters and delivery constraints. A slight gap is the lack of specifying the exact response format (e.g., JSON object), but this is acceptable for a creation 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?

Although the schema already describes all parameters with 100% coverage, the description adds meaningful examples and clarification for each type (e.g., sec_8k items, fred_series series_id) and for delivery channels (e.g., webhook HMAC signing, email validation). This enriches the schema definitions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This identifies the specific verb (create) and resource (subscription), and distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

The description covers prerequisites (requires Pipeworx OAuth account, not for BYO/anonymous) and lists supported types and delivery channels, giving clear context for when to use the tool. However, it does not explicitly contrast with sibling tools like ask_pipeworx or recent_alerts, leaving some inference required.

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

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

Annotations already declare safe, idempotent, read-only behavior. The description adds valuable details: returns 'category-bucketed example questions ... each with the exact tool + argument shape' and mentions the live catalog. 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 well front-loaded with common queries. It is somewhat long but each sentence adds value. Could be slightly more concise without losing information.

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

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

Despite no output schema, the description thoroughly explains the return format (category-bucketed examples with tool+argument shape) and mentions the catalog size. Covers all necessary context for an onboarding tool with simple input.

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% (1 parameter with description). The description adds that omitting topic gives a 'cross-category spread' and lists possible values (finance, pharma, etc.) which mostly repeat the schema. Minimal additional meaning 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 starts with common user queries ('What can I ask Pipeworx? / what is Pipeworx good for?') and precisely states the action: 'Returns category-bucketed example questions ... with the exact tool + argument shape'. It positions the tool as the 'onboarding entry point', clearly distinguishing 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?

Explicit 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'. Also explains the optional topic parameter for focus. Lacks explicit 'when not to use', but context is clear enough.

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

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

Annotations already indicate write intent (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds context: deactivation, not deletion, and ownership enforcement, which goes beyond annotations. 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 concise sentences, no wasted words. The main action and key constraints are front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description covers all necessary context: action, constraints, side effects, and relation to another tool (recent_alerts).

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

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

Schema has 100% coverage with a description for the 'id' parameter. The description adds no further parameter meaning beyond 'by id'; the ownership and deactivation details are about tool behavior, not the parameter itself. Baseline 3 is appropriate.

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

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

The description clearly states the tool cancels a subscription by id, with the verb 'Cancel' and resource 'subscription'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by noting the deactivation behavior and ownership enforcement.

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 specifies that ownership is enforced, meaning only your own subscriptions can be canceled. It implies when not to use (others' subscriptions) and mentions historical events stay available via recent_alerts, but does not explicitly name alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it explains the critical distinction between could_not_verify (check did not happen) and unsupported (no source coverage), warns callers against treating could_not_verify as evidence, and describes the two-path logic and output verdicts. This goes well beyond the read-only/idempotent annotations.

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

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

The description is dense but well-organized, front-loaded with query examples and then purpose, pathway, output, and caller warnings. Every sentence contributes useful information. It is longer than typical for a 2-param tool, but the dual-path behavior and critical error semantics justify the length.

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

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

Given there is no output schema, the description fully explains return values (verdict types, evidence with citation, reasoning) and error semantics. It covers the two source paths, the tolerance behavior, and the replacement of multiple sequential calls. The tool's complexity is matched by a complete and self-contained description.

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 both parameters (claim and tolerance_pct) are well-documented in the schema with examples and constraints. The description does not add meaning beyond the schema; it only references tolerance behavior indirectly. Baseline 3 is appropriate when the schema carries the parameter semantics fully.

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 natural-language query examples and explicitly states the tool performs 'natural-language claim verification against authoritative sources.' It clearly distinguishes from sibling tools by specifying the verification task and the dual-path routing (SEC EDGAR for financial claims, grounded pipeline for other claims), which separates it from generic ask/research 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the automatic routing for different claim types. However, it does not name specific alternative tools for non-verification tasks (e.g., deep_research), so there's a slight gap in explicit when-not-to-use guidance.

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