Mediastack

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

Annotations already indicate read-only, idlempotent, and non-destructive nature. The description adds valuable behavioral details: default free model, BYO key for Anthropic with direct billing, and return format. No contradiction.

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

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

The description is a single, well-structured paragraph that front-loads key information (purpose, default model, optional behavior). Every sentence adds value; no wasted words.

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

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

For a tool with 4 parameters, no output schema, and rich annotations, the description fully explains return format (per-model object + combined), use cases, optional parameters, and model costs. No gaps.

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

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

Schema coverage is 100%, but the description adds meaning beyond names/descriptions: default model behavior, API key pass-through, and context disambiguation. This justifies a score above baseline 3.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility. It uses specific verbs like 'probe' and 'score', specifies the default model, and differentiates from siblings like 'scan_competitor_ai_presence'.

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

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

The description provides use cases (AI-marketing audits, brand checks, monitoring) and explains how to use the tool with default or Anthropic models. It lacks explicit when-not-to-use guidance but offers clear context and optional parameters.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behavioral traits: it automatically routes to the right tool, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also mentions it is 'one fast call' and works on every tier. These details add significant value without contradicting the annotations.

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

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

The description is long but well-structured and front-loaded with the key message 'PREFER OVER WEB SEARCH.' While it contains a detailed list of data types and multiple examples, every sentence adds useful context. It is somewhat longer than necessary, but the organization is logical and no sentence is pure filler.

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

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

Given the tool's complexity, the description is remarkably complete. It explains the return value (structured answer with citation URIs), covers a broad range of use cases, gives examples, and clearly instructs when to step up to alternatives. There is no output schema, but the description sufficiently covers what the agent will receive. No gaps in essential 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 documents all six parameters with 100% coverage, including that they are aliases for 'question.' The description does not add any new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate because the schema carries the full burden and the description does not need to compensate.

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

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

The description clearly states what the tool does: it routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citation URIs. It uses a specific verb ('routes', 'returns') and explicitly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives. The purpose is unmistakable and immediately differentiates 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?

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions — this is the default entry point.' It also provides alternatives with specific conditions: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. Trigger phrases and concrete examples further clarify the appropriate use cases.

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

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

Beyond the read-only/idempotent annotations, the description discloses the experimental, live-updating nature of routing candidates, the current inactive status, the identical response shape, and the fact that it is a full working router rather than a fallback. This adds substantial 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?

Three sentences, front-loaded with the tool's identity, and each sentence adds essential information (purpose, current status, usage, and fallback behavior). No wasted words.

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

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

For a simple one-question-parameter tool with no output schema, the description is complete: it covers purpose, experimental behavior, current parity with ask_pipeworx, and usage guidance. It even explains what it is not (a fallback), which prevents misinterpretation.

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 covers all six parameters with descriptions as aliases for 'question', giving 100% coverage. The description adds no new parameter semantics beyond referencing that it uses the same arguments as ask_pipeworx, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a beta universal router identical to ask_pipeworx, with experimental routing improvements. It distinguishes itself from siblings by its experimental nature and explicit current parity with ask_pipeworx.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes that no candidate is currently active so it matches ask_pipeworx exactly. It lacks explicit when-not-to-use guidance or direct comparison to ask_pipeworx_grounded, but the main usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context beyond that: it states the extraction is restricted to the tool result, details the success output structure (evidence, confidence, source), enumerates the refusal_reason values, and mentions an extra LLM 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?

The description is dense but every sentence earns its place. It starts with the core purpose, explains the mechanism, details the return format and refusal reasons, provides use cases, and ends with cost guidance. No fluff or redundancy; it is front-loaded with the primary purpose.

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

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

Given the tool's complexity and the absence of an output schema, the description compensates thoroughly by explaining return values, failure modes (refusal reasons), usage scope, and cost tradeoffs. It also names sibling ask_pipeworx for context. The description is complete for the intended agent behavior in high-stakes scenarios.

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

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

Schema description coverage is 100% with all six parameters explained as aliases for 'question.' The description does not add parameter-specific details beyond what the schema already provides, and the schema is entirely self-explanatory. Baseline 3 is appropriate since the description adds no additional parameter semantics.

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

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

The description states a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' and further clarifies that it 'EXTRACTS the answer using ONLY what the tool result contains.' It clearly distinguishes from sibling ask_pipeworx by emphasizing grounding, evidence, and explicit refusal, leaving no ambiguity about the tool's unique purpose.

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

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

Explicit when-to-use guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also names the alternative: 'prefer ask_pipeworx for casual lookups,' and notes the cost tradeoff ('Costs one extra LLM call'). This clearly positions the tool against its sibling.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral details: fan-out logic, response shapes, resolver contract, parent event extractor, safety mechanisms, closed market handling, wide spread tradeability, cancellation rule parsing. 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?

Description is long but well-structured with sections (fan-out examples, response shapes, resolver contract). Every sentence provides valuable information for a complex tool. Slightly verbose but justified given the tool's scope.

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

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

No output schema, so description fully explains return values (result.market, result.analysis, result.evidence) and edge cases (low-confidence, closed markets, wide spreads, resolution rules). Covers all necessary context for proper use.

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

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

Schema coverage is 100% with descriptions for each parameter. Description adds extra meaning: explains market can be slug, URL, or question text; depth enum values are elaborated ('quick = 2-3 sources, thorough = full fan-out'); include_raw effect explained. Adds significant value beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). Distinguishes from siblings like polymarket_edges which are narrower.

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

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

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). Provides examples per category. Does not explicitly mention when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

Description is front-loaded with trigger phrases and structured as: trigger list, behavior, data details, and efficiency claim. Every sentence is meaningful, though slightly long. Could be tightened but remains clear and well-organized.

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

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

Given no output schema, the description explains return format (paired data, citation URIs) and result ordering. It covers purpose, input examples, data sources, behavioral nuances, and efficiency benefits. Completes all needed context for correct tool invocation.

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

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

Schema coverage is 100%; both parameters are documented in the schema. The description adds meaning beyond the schema: explains what each enum value ('company', 'drug') retrieves, provides example inputs with tickers/CIKs and drug names, and reinforces the 2–5 item constraint. This adds value beyond baseline 3.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs, with highly specific verb phrases ('compare', 'rank', 'head to head') and explicit resource (SEC EDGAR/XBRL financials, FAERS/FDA data). It distinguishes from siblings by noting it replaces 8–15 sequential lookups and should be preferred over single-pack lookups.

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

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

Explicitly provides natural-language triggers (e.g., 'Compare X and Y', 'which is bigger', 'rank these companies') and clear usage preference: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This gives strong guidance on when to use this tool vs. alternatives.

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

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

Even with strong annotations, the description adds substantial behavioral context: it details return structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]), latency (15-90s), account/plan constraints, semantic excerpting behavior, and the guarantee that cited URIs are always fetchable. It also clarifies the nondestructive nature implied by annotations without contradicting them.

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

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

The description is long but every sentence serves a purpose: account requirements, core capability, comparison to alternatives, depth semantics, output format, limitations, and performance. It is front-loaded with the most critical constraint (account) and structured logically. No filler or redundancy 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?

For a complex tool with no output schema, the description is exceptionally complete. It covers purpose, when to use, prerequisites, parameter semantics, return envelope, failure modes (gaps), contradictions, citation resolvability, and expected latency. It even addresses edge cases like large records being semantically excerpted rather than head-truncated.

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

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

The schema already documents both parameters, but the description goes far beyond: it explains the `depth` values in detail ('quick=3 (single hop), standard=5... thorough=8') and clarifies that `question` accepts broad/multi-part natural language because decomposition is the point. This materially aids correct invocation beyond the schema descriptions.

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

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

The description clearly states the tool performs 'multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with a specific verb 'research' and resource. It explicitly distinguishes itself: 'this is NOT open-web search', and contrasts with sibling ask_pipeworx, making its unique purpose unmistakable.

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

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

The description gives explicit usage criteria: 'Best for broad/multi-part questions over structured data' and directly names alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states account prerequisites and when the tool will return empty gaps, providing complete when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable detail about return format (top-N tools with full schemas, ready to call) and no second lookup needed, enhancing 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?

Front-loaded with purpose, followed by domains, then return format and usage guidance. Slightly verbose but well-structured and each sentence serves a clear role.

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?

High coverage given no output schema: explains what it returns, when to use, and provides example queries. For a discovery tool, this is sufficiently complete.

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

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

Schema coverage is 100% with examples, so the description adds minimal parameter-specific value beyond listing aliases and example queries already present 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 'Find tools by describing the data or task' and lists specific use cases and domains (SEC filings, financials, etc.), distinguishing it from sibling tools as a discovery tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear guidance on when to use it for exploration rather than direct answers.

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 rich behavioral context beyond annotations: lists data sources (SEC, XBRL, USPTO, news, GLEIF), return fields, limitations (USPTO sunset), and input constraints. No contradiction with annotations.

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

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

Front-loaded with example queries and structured bullet-style listing of returned data. Slightly verbose but each sentence adds value; could be tighter but still efficient.

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

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

For a complex tool with no output schema, the description is remarkably complete: it enumerates all return fields, data sources, and edge cases (e.g., patent API sunset). No gaps for an agent to be confused about.

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. Description adds value by explaining enum options (type: only 'company'), providing examples for value, and clarifying that names are not supported—going beyond 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 verb+resource ('full cross-source profile of a US public company'), provides multiple example queries, and explicitly distinguishes it from chaining other tools, making the purpose unambiguous.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack...' for holistic views, advises using resolve_entity if only a name is available, and thus provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data but does not elaborate on permanence or side effects. It adequately complements annotations without contradiction.

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

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

Two sentences, front-loaded with the core action. No unnecessary detail. Every sentence adds value: first states purpose, second gives usage guidance and links to siblings.

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

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

Given the tool's simplicity (one param, no output schema) and annotations, the description covers purpose, usage, and relationship to siblings. Missing details like error behavior (e.g., key not found) are minor for this context.

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

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

Schema coverage is 100% with a clear description and example for the 'key' parameter. The description only mentions 'by key' without adding new semantics, so it meets the baseline for high coverage.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It identifies the resource (memory) and the specific operation (delete). Mentioning 'Pair with remember and recall' helps distinguish from related tools, though not exhaustively.

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

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

The description explicitly lists when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' It does not provide explicit when-not-to-use or alternatives, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds the process details: fetches page, extracts title/description/key links, emits standard llms.txt format, and output is a text blob ready to drop at site-root. 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?

Description is three sentences with no filler. Information is front-loaded: first sentence states purpose, second explains process, third lists use cases. 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 tool with 2 parameters, no output schema, and comprehensive annotations, the description provides sufficient context: purpose, process, output format, and use cases. No gaps remain.

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

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

Schema coverage is 100% and description does not add meaning beyond what schema already provides for both 'url' and 'max_links'. The baseline of 3 is correct given high coverage.

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

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

Description uses specific verb 'generate' and resource 'llms.txt file', clearly indicating the tool's output. It distinguishes from all 38 sibling tools by describing a unique function (generating an AI crawling index file). No sibling tool appears to do this.

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

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

Explicitly lists three concrete use cases: getting a client's site indexed, drafting for own project, auditing competitor. Does not state when not to use or provide alternatives, but the provided context strongly implies appropriate usage.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about return format (titles, descriptions, sources, URLs), which is sufficient beyond annotations.

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

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

Two tightly written sentences with zero redundancy. The primary action is front-loaded, and every word 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?

The description provides basic usage and output but lacks explicit differentiation from similar tools (e.g., 'search_news') and has parameter inaccuracies, leaving gaps for an agent to decide when to use this tool.

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

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

Despite 100% schema coverage, the description introduces a non-existent parameter 'language' and uses singular forms ('category', 'country') that do not match the schema's actual parameters ('categories', 'countries'), potentially misleading an agent.

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

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

The description clearly states the tool retrieves the latest news headlines and mentions optional filters. It distinguishes from sibling 'search_news' by implying focus on current headlines, but does not explicitly differentiate.

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 advises optional filtering by category, country, or language, but does not specify when to avoid this tool or suggest alternatives like 'search_news' for keyword-based searches.

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, and idempotentHint. The description adds value by specifying returned fields and the concept of 'active' subscriptions, but does not introduce new behavioral traits beyond these.

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 that front-load the purpose and follow with usage guidance. No redundant information.

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

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

The tool is simple with one optional parameter and no output schema; the description lists all return fields. Combined with rich annotations, the definition is fully complete for an AI agent to use correctly.

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

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

Schema coverage is 100% with a well-described boolean parameter (include_inactive). The description does not elaborate on parameter usage, but the schema already provides adequate meaning, so baseline 3 applies.

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

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

The description explicitly states the tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, etc.), clearly distinguishing it from sibling tools like subscribe or 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 provides concrete use cases: 'review what you're monitoring before adding more' and 'find an id to cancel', offering clear guidance on when to invoke this tool versus alternatives.

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

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

The description discloses multiple behavioral traits beyond the annotations: rate-limit ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), side effects ('The team reads digests daily and signal directly affects roadmap'), and the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later...'). These details are not in the annotations, fully carrying the transparency burden. There is no contradiction with the annotations.

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

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

The description is moderately long but every sentence earns its place: it covers purpose, usage, scope, formatting, token workflow, team process, rate limit, and cost. The first two sentences front-load the core purpose and triggers. Slight redundancy (e.g., the first sentence already says 'broke, missing, or needs to exist' and the usage list repeats similar categories) prevents a perfect score, but the structure is logical and scannable.

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 (4 parameters, nested object, no output schema), the description is exceptionally complete: it explains the entire feedback loop (file via arguments, receive claim_token, later check status), clarifies what qualifies as valid feedback, distinguishes from other MCP servers, and notes operational constraints (rate limit, quota impact). The absence of an output schema is mitigated by explicitly stating the return token and its meaning.

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?

While the schema already covers 100% of parameters with descriptions, the description enriches understanding, especially for claim_token and context: it explains the token's round-trip workflow and provides an example call. It also instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which adds crucial semantics to the message and context fields that the schema alone does not convey.

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

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

The description opens with 'Tell the Pipeworx team something is broke, missing, or needs to exist,' explicitly naming the action (feedback) and the specific resource (Pipeworx team). It distinguishes itself from sibling tools by focusing exclusively on user feedback for the current Pipeworx connection, not on research or entity operations. The scope limitation ('ONLY for tools served by this Pipeworx connection') further clarifies its unique niche.

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

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

The description provides explicit usage triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions, directing users to file with another server if the tool isn't Pipeworx-specific, and offers a fallback test ('Not sure? Pipeworx tool names are the ones this connection lists'). This is exemplary when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, etc.), the description adds valuable behavioral details: data source (CF analytics-engine), no PII, cached 5min-1h, and self-aggregating signal. No contradiction with annotations.

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

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

The description is concise (5 sentences) and well-structured, starting with core functionality, then bullet-point use cases, and ending with technical details. No unnecessary words.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description covers purpose, use cases, data provenance, caching, and parameter semantics. It is fully adequate for the agent to understand and invoke the tool correctly.

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

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

The description adds meaning to the single parameter 'window' beyond the schema's enum options, explaining that shorter windows show current trends and longer windows show steady-state demand. Schema coverage is 100%, so baseline is 3, but the extra context earns 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 what the tool does: returns top tools, packs, and call volume on Pipeworx over a recent window. It uses a specific verb ('Returns') and distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on trending usage 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 explicitly lists three use cases (discovering hot data, confirming canonical tools, checking alignment) and explains window choices. It does not mention when not to use or compare directly with siblings, but the context is sufficient for selection.

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

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

Annotations are readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: semantic anchor, partition filter, fill check against CLOB depth, and realizable edge calculation. No contradictions.

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

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

The description is dense and well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While lengthy, every part earns its place. Minor redundancy (e.g., mention of fill check twice).

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 provided, but the description thoroughly explains response fields (opportunities[], partition_check, suggested_trade, fill_check details). Covers behavior, limitations, and integration with other 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 descriptions for both event and topic. The description adds value by explaining the modes, providing example inputs, and detailing behavior (e.g., cross-event scanning dependencies).

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, with explicit modes (no args, event, topic) and examples. It is specific and distinguishes from sibling tools.

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

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

Provides detailed guidance on when to use each mode (event recommended for specific markets, topic for cross-event scanning), explains fill check, and mentions custom sizing via polymarket_fill_risk. Lacks explicit 'when not to use' or direct comparison with other sibling tools like polymarket_edges.

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

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

Annotations declare readOnlyHint, idempotentHint, etc., and the description adds rich behavioral context: caching (1h at KV level), segment logic, diagnostics for empty results, and trade details. 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?

Front-loaded with core purpose but overall very long with extensive details on segments and formulas. Could be more concise by moving some details to external references.

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 thoroughly documents response structure (by_segment, fed_candidates, diagnostics) and caching behavior. All 9 parameters are explained with usage context. Complete for a complex tool.

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

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

Baseline 3 due to 100% schema coverage; description adds value by explaining real-world context (e.g., slippage_pp mentions Polymarket fees, min_liquidity gives example, min_partition_leg_kelly explains interaction with min_kelly). Exceeds baseline.

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

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

Description clearly states the verb 'scan' and 'return', resource 'Polymarket markets', and the specific outcome 'opportunities where Pipeworx data disagrees with market price'. It distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement.

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 built for 'what should I bet on today' and describes how agents discover opportunities without paging. However, it lacks explicit when-not-to-use or comparisons to siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description adds significant behavioral context beyond annotations: snapshot TTL (60 days), decay computation from daily closes (not intraday), response structure with detailed field meanings (trend values, decay_pp_per_day), and handling of gaps. Annotations already declare read-only, idempotent, and non-destructive, and the description fully aligns.

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 question and then breaks down the response into tracked, expired, and snapshot_dates. Although it is verbose, every sentence adds value, and the structure is logical. Minor reduction for length but not excessive.

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

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

Given the lack of output schema, the description fully explains the return structure, including all fields and their interpretations (trend values, decay_pp_per_day, lifespan_days, snapshot_dates). It also covers limitations (TTL, snapshot start, decay from closes). No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the default values and clamp of 'days' and mentions 'snapshot family' for 'window', but does not add new semantic meaning beyond what the schema already provides. No extra nuance or usage hints are given.

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: it provides edge persistence and decay telemetry. The verb 'track' is implicit in the title and description, and it explicitly answers a specific question about edge longevity. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical persistence and trend analysis.

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

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

The description implies when to use the tool ('Answers how long has this edge existed and is it shrinking?') but does not explicitly state when not to use it or compare it to alternatives. The context is clear enough for an agent to infer usage, but lack of explicit exclusions prevents a perfect score.

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

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

Despite annotations already providing readOnlyHint, idempotentHint, and non-destructive flags, the description adds extensive behavioral context: it walks the order book ladder, returns top-of-book and VWAP fills, slippage, and warns about forced directional risk. Since no output schema exists, the description fully compensates.

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 bold headers for modes, but it is verbose with repeated warnings about partial fills and directional risk. It could be slightly more concise without losing clarity, but the length is justified by the tool's complexity.

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

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

Given no output schema, the description thoroughly documents all return fields for both modes, covers edge cases (thin legs, clamping), and explains the dominant loss mode (unhedged directional position). It is fully complete for evaluating tool suitability.

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 significant value by explaining the dual meaning of 'side' (single-market vs basket auto-detection), the different interpretation of 'size_usd' between modes, and the requirement for exactly one of 'market' or 'event'.

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 verb (fill risk check) and resource (live CLOB order-book depth), distinguishing between single-market and basket modes. It is specific and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by focusing on capturability rather than signal generation.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the risk of partial fills converting arb to directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

The description significantly enriches beyond annotations (readOnlyHint, etc.) by detailing safety fields (compatibility_warning, temporal_alignment, skipped counters) and explaining common pitfalls like non-equivalent bet shapes or temporal mismatches. This fully discloses behavioral traits and edge cases.

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 a clear summary, mode explanation, response fields, and a closing caveat. It is front-loaded with the core purpose, and each sentence adds necessary behavioral or usage guidance. Slight reduction could be possible but quality justifies 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 no output schema, the description adequately explains the response structure (venue prices, spread, safety fields). It covers edge cases like incompatible bets and temporal mismatches. For a complex cross-venue tool, it is sufficiently complete to guide correct invocation.

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

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

With 100% parameter coverage in the schema, baseline is 3. The description adds value by clarifying that 'topic' is a pre-mapped shortcut with listed values, and that explicit parameters override the default mapping. This goes beyond the schema's simple type and description.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It specifies two modes ('topic' shortcuts and explicit ticker/slug) and explains the response, making it distinct from siblings like 'polymarket_arbitrage' which focuses on single-venue 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 provides clear context on when to use the tool (comparing prices across venues) and includes warnings that most pre-mapped topics return compatibility warnings, signaling limited applicability. However, it does not explicitly state when not to use it or name alternative tools for different 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 declare read-only and idempotent behavior. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) which is not in annotations. No contradictions.

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

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

Three concise sentences that front-load the main purpose, with no wasted 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?

For a simple tool with one optional parameter and no output schema, the description fully covers usage, scoping, and relationships with siblings. No gaps.

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

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

Schema has 100% coverage with a clear description for the 'key' parameter. The description reinforces that omitting the key lists all keys, but adds little beyond the schema.

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

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

Description clearly states the verb (retrieve/list) and resource (saved memories). It distinguishes from siblings like 'remember' and 'forget' by explicitly mentioning them and contrasting the action.

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

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

Describes when to use (looking up previously stored context) and provides context about scoping to an identifier. Does not explicitly state when not to use, but the pairing with 'remember' and 'forget' implies 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?

Adds context beyond annotations: describes returned fields, mark_read side effect, and mentions the same feed available via REST. 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?

Concise and front-loaded: first sentence captures purpose, no fluff, every sentence adds value.

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

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

Covers purpose, parameters, return fields, behavior, and alternative access, all without an output schema. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description elaborates on type, since, and mark_read, but omits limit and unread_only, adding partial value.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts, 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?

Provides guidance on filtering by type and since, setting mark_read, and notes polling works fine, with an alternative REST endpoint. Lacks explicit when-not-to-use but is informative.

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, but the description adds detailed behavioral context: fans out to multiple APIs, fallback logic, USPTO soft-fail, and return structure.

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 informative but slightly long. Starts with example queries which is helpful, but some repetition could be trimmed.

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

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

Despite no output schema, the description explains return structure comprehensively. Handles edge cases like fallback and soft-fail.

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

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

All three parameters are fully described in the schema, and the description adds extra context: 'since' format with examples, 'value' as ticker or CIK, and 'type' as 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?

Clearly states the tool returns recent changes for a company from multiple sources (SEC filings, news, patents) and distinguishes from sibling tool 'entity_profile'. Examples of queries help clarify use cases.

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 examples and recommends 'entity_profile' for static profiles. Also explains fallback behavior for news sources under rate limiting.

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 mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds key behavioral details: key-value pair scoped by identifier, persistence differences between authenticated and anonymous sessions (24h), and pairing with recall/forget. No contradiction with annotations.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, usage context, durability behavior, and pairing instructions.

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 simplicity of the tool (2 required params, no output schema), the description covers all essential aspects: storage mechanism, scope, persistence duration, and relationship with sibling tools. It is fully sufficient for an agent to use correctly.

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

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

Schema description coverage is 100% (both key and value have descriptions). The description reinforces the schema by providing example keys and values, but adds limited new semantic meaning beyond the schema's own 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 'Save data the agent will need to reuse later' with concrete examples (resolved ticker, target address, user preference). It distinguishes itself from sibling tools by mentioning 'Pair with recall to retrieve later, forget to delete.'

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 advises use when 'you discover something worth carrying forward' and contrasts with recall/forget. It provides clear context but does not explicitly state when not to use the tool.

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

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

The description adds substantial behavioral detail beyond the readOnlyHint/idempotentHint annotations: identifiers are labelled with their source, unresolved identifiers are explicitly listed under `unresolved`, and LEI/FIGI enrichment degrades gracefully if GLEIF/OpenFIGI is unavailable. It also notes that each call cascades through multiple lookup endpoints, which sets expectations about cost and complexity.

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 densely packed with useful information. It front-loads examples and the 'Use FIRST' directive, then details supported types and behavioral caveats. Every sentence contributes value, though some trimming could make it more digestible.

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

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

Given two parameters and no output schema, the description covers what the agent needs: return behavior (source-labelled IDs, unresolved list), graceful degradation, and supported entity types. It also notes that resolve_entity replaces 2-3 manual lookups, giving a full picture of the tool's scope and limitations.

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

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

With 100% schema coverage, both parameters are documented, but the description enriches meaning with concrete examples ('ticker (AAPL), CIK (0000320193), or name') and explains the value parameter's behavior per type. This goes beyond the schema's terse descriptions, earning a score above the baseline.

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

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

The description clearly states the tool's verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also differentiates from siblings by saying 'Use FIRST whenever you have a name but need an ID,' which contrasts with tools like entity_profile that likely take an ID as input.

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

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

Explicit usage guidance is provided: 'Use FIRST whenever you have a name but need an ID.' It also specifies supported types ('company' and 'drug') and acceptable input formats (ticker, CIK, name, brand/generic), giving clear context for when to invoke this tool versus alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, non-destructive. The description adds that it calls ai_visibility_check per entity, returns a ranked list with score, confidence, and signal density, and treats the first entity as subject. No contradictions. Description adds meaningful context beyond annotations.

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

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

The description is three concise sentences. First sentence states purpose, second explains mechanics, third gives example. No superfluous words, well 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?

Though there is no output schema, the description clearly states the return format: 'ranked list with score, confidence, signal density per entity.' It also explains the tool probes each entity with ai_visibility_check, providing enough context for an agent to understand expected behavior.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra semantics: 'First entry treated as the 'subject' for narrative; rest are competitors.' This clarifies usage beyond the schema's generic 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks by score. It distinguishes itself from siblings like ai_visibility_check (single probe) and compare_entities (which may have different focus) by specifying its competitive audit purpose.

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

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

The description gives a concrete use case: 'competitive AI-marketing audits' and an example question. It implicitly differentiates from single-entity probes by noting side-by-side comparison. However, it doesn't explicitly list when not to use or mention alternatives beyond the context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds rich behavioral context: fans out to two services, returns specific fields (summary block, per-advisory detail, links, alternative versions), mentions timing (bundlephobia first measurement takes 5-30s), and explains graceful degradation (sources_failed will list timeout, rest still returns). 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 a single paragraph that packs a lot of information. It is front-loaded with the core purpose. While dense, every sentence serves a purpose (use case, return structure, ecosystem scope, timing caveat). Slightly long but justified by the tool's complexity; could be shorter but acceptable.

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 (composite check, two services, multiple return types, partial failures, ecosystem limitation) and absence of an output schema, the description covers all necessary aspects: what is returned (fields, advisories, links, alternatives), timing, graceful degradation, and ecosystem scope. It is fully complete for an agent to use correctly.

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

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

Schema covers package and version with 100% description. The description adds value by noting that scoped packages (e.g., @types/node) are accepted for the 'package' parameter, which is not explicit in the schema. It also reinforces version defaults. Overall, it clarifies acceptable inputs beyond schema.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia, with a specific verb ('scan') and resource ('dependency'). It distinguishes from sibling tools by specifying the npm ecosystem and the exact use case ('should I add this npm package?'). The function is unique among siblings, which include generic 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?

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small' and gives a concrete example ('what does adding lodash cost me'). Also tells when not to use: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. Provides guidance on partial failures and timing.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds return value composition (headlines, descriptions, sources, dates) beyond annotations, providing useful behavioral context.

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

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

Two sentences, front-loaded with the primary action, no extraneous 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?

For a search tool with output schema, the description covers key inputs and outputs. Lacks mention of pagination or sorting, but overall adequate given schema richness.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates filter options and categories but adds minimal new meaning beyond what the schema's parameter descriptions already provide.

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 searches news articles by keywords, with a specific verb and resource. It distinguishes from sibling 'latest_news' by emphasizing keyword-based search and optional filters.

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

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

The description explains when to use (search with keywords and optional filters) but does not explicitly contrast with alternative tools like 'latest_news' or provide when-not-to-use guidance.

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

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

Adds details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, character offset guarantees. Annotations already state safe and idempotent, but description enriches with technical specifics.

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 under 100 words, efficiently packing purpose, usage, and technical details. No filler.

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

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

Covers all essential aspects: purpose, usage, technical constraints, output format (offsets, scores). No output schema but description sufficiently explains returns.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats schema details (char limit, limit range) but adds query examples, which provides moderate added value.

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

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

Clearly states it performs semantic search inside a fetched record, with specific output (passages, offsets, scores). Distinguishes from siblings like search_news and ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too large for prompt, and pairs with ask_pipeworx_grounded. Provides clear when-to-use guidance.

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

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

Annotations indicate non-read-only, open-world, idempotent, non-destructive. The description adds context: returns subscription id, webhook secret returned once, auto-disabled after 10 consecutive failures. No contradictions; adds value beyond annotations.

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

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

The description is comprehensive but not overly verbose. It is front-loaded with the core purpose, then breaks down types and delivery in an organized manner. Minor redundancy could be trimmed, but overall efficient.

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

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

Given no output schema, the description explains the return value (subscription id) and covers all aspects: authentication, type-specific parameters, delivery options with constraints, and failure behavior. Very complete 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?

With 100% schema coverage, the description still adds meaning: textual examples for each type's params, delivery channel details (email pattern, SMS verification, webhook signing). This goes beyond the schema's bare 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 'Create a proactive monitoring subscription to a live-data event stream' and directs the agent to its purpose. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation. Specific verb and resource are present.

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 context: requires a Pipeworx OAuth account (anonymous/BYO cannot persist subscriptions), details supported types and parameters, and notes delivery channel constraints (phone verification, SMS cap). It does not explicitly state when not to use, but the guidance is strong.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds context about returning category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog, without contradicting annotations.

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

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

Description is front-loaded with the core purpose and includes example trigger questions but is slightly lengthy. Still, 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?

Despite no output schema, description fully explains return format (category-bucketed example questions with tool+argument shapes) and usage context (onboarding). No gaps.

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

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

Schema covers the single optional parameter topic with 100% coverage, but description enriches by listing example focus areas and explaining the effect of omitting vs. providing the parameter.

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

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

Description clearly states the tool is an onboarding entry point for discovering what Pipeworx can do, returning categorized example questions with tool+argument shapes. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying it provides ideas and examples.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with no arguments or with a topic. Lacks explicit when-not statements but gives clear context for use.

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

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

The description adds value beyond annotations by disclosing ownership enforcement, deactivation vs. deletion, and retention of historical events. It does not contradict annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) and provides behavioral context that annotations alone do not cover.

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

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

The description is two sentences: the first states the purpose, the second adds constraints and side effects. Every sentence contributes necessary context, with no redundant or extraneous 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?

For a simple tool with one parameter and no output schema, the description covers the action, ownership rule, deactivation behavior, and linkage to 'recent_alerts.' It is fully sufficient for an AI agent to understand and correctly invoke the tool.

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

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

The schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description merely says 'Cancel a subscription by id,' which adds no new semantic meaning beyond the schema. With 100% schema coverage, baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' using a specific verb (cancel) and resource (subscription). It adds context about ownership enforcement and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by clarifying the action and constraints.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use and implies when not to. It also mentions that the row is deactivated, not deleted, linking to 'recent_alerts' for history, but lacks explicit exclusions or alternatives for other scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond this by explaining the two routing paths, the exact verdict set, the meaning of 'could_not_verify' (with verification_error structure) versus 'unsupported', the percent-delta math, and the inclusion of verbatim evidence and citations. This rich behavioral context is not available in annotations.

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

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

The description is dense but well-structured: trigger phrases first, then usage, then internal routing, then output semantics, then crucial caller warnings. Every sentence adds operational value; the warning about 'could_not_verify' is especially important. It is appropriately sized for the tool's complexity and fronts the purpose immediately.

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

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

Despite having no output schema, the description fully explains the return payload (verdict, actual value with citation, reasoning) and the error cases. It also covers the two routing paths and how they differ. For a tool with this complexity, the description leaves no significant gaps for an agent to invoke and interpret the result 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 both parameters are documented in the schema. The description adds meaningful context by explaining how tolerance_pct overrides the claim's implied tolerance, the accepted range (0.5–50), and its use in hallucination detection. It also ties the parameter to the percent-delta grading logic, which enhances understanding beyond the raw schema.

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

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

The description clearly defines the tool as natural-language claim verification with specific trigger phrases like 'fact check' and 'verify the claim that…'. It states the resource (claims) and the action (validate against authoritative sources), and distinguishes it from siblings by framing it as a single-call replacement for a multi-step verification pipeline.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is a clear usage directive. It also gives internal routing guidance (SEC EDGAR fast path vs. grounded pipeline) and when to set tolerance_pct for hallucination detection. However, it does not explicitly name when-not-to-use alternatives like ask_pipeworx_grounded, so it stops short of full exclusion guidance.

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