Jina Reader

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds return format details (per-model {score, confidence, signals, raw_response} + combined view) and notes Anthropic billing responsibility, enhancing transparency beyond annotations.

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

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

Four concise sentences with no redundancy. Front-loaded with main purpose, then model details, return format, and use cases. Every sentence serves a purpose.

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

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

Despite no output schema, the description adequately covers return format. It explains authentication for Anthropic and provides usage context. All necessary information for invocation is present.

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 value by clarifying default model for 'models', free usage, and BYO key for Anthropic, providing context beyond schema descriptions.

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

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

The description clearly states the tool probes LLMs for brand/product visibility and scores it, with specific verb (probe, score) and resource (models, visibility). It differentiates from siblings by focusing on visibility scoring rather than entity profiles or competitive scans.

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 concrete use cases (marketing audits, pre-launch checks, competitive monitoring) and explains default model vs. Anthropic with key. Does not explicitly state when not to use, but context implies appropriate 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?

Given strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds meaningful behavioral context: it routes to internal tools, fills arguments, returns structured answers with citations, and works 'on every tier' with 'one fast call'. These details go beyond the annotations, though it does not deeply cover failure modes or response 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 long but information-dense; every section earns its place by covering purpose, use cases, examples, and alternatives. It is front-loaded with the key directive ('PREFER OVER WEB SEARCH') and maintains clear structure. Minor redundancies like 'START HERE' and 'default entry point' are acceptable for a tool intended as the primary entry point.

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 covers the essential contract: input types, supported domains, output nature (structured answer with stable citation URIs), and explicit guidance on when to escalate. It does not detail pagination, error formats, or source-level citation behavior, but it is sufficiently complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by providing concrete query examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and trigger phrases that clarify what makes a good 'question' value, going beyond the schema's simple alias documentation.

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

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

The description clearly states the tool's function: it routes questions to one of 5,529 tools across 1,455 sources and returns structured answers with pipeworx:// citation URIs. It also explicitly distinguishes itself from sibling tools ask_pipeworx_grounded and deep_research, making its role as the default entry point 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 provides extensive when-to-use guidance: it should be preferred over web search for factual/current/historical data and used for common trigger phrases like 'what is', 'look up', or 'find'. It explicitly names alternatives ('ask_pipeworx_grounded' for hallucination-resistant single answers, 'deep_research' for broad multi-part questions) and conditions for stepping up.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description discloses that the tool is experimental, may have candidate routing improvements enabled live, and that results are compared against the stable router. This adds meaningful behavioral context, though it does not detail what a candidate improvement might change beyond routing.

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

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

The description is four sentences, each providing useful information: beta nature, current state, usage guidance, and a clarifying statement about fallback. It is front-loaded with the core purpose. Slightly longer than necessary but not wasteful.

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 rich annotations and fully described schema, the description adds crucial context about the beta status, current equivalence to ask_pipeworx, and the experimental routing comparison. It does not explicitly describe the response format, but it references 'same response shape' as ask_pipeworx, which partially addresses this. Overall, it is sufficiently complete for 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?

The input schema already provides full coverage of all six parameters (all aliases for 'question'). The description merely says 'same arguments', which reinforces but does not add meaning beyond the schema. Since schema coverage is 100%, a 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 it is a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by emphasizing the experimental routing improvements. However, it relies on prior knowledge of what ask_pipeworx does, so it is not fully self-contained.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that no candidate is active right now, so it currently matches ask_pipeworx exactly. This provides clear context for when to use the tool versus the stable alternative, though it does not explicitly discuss alternatives like ask_pipeworx_grounded.

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 helpful annotations (readOnlyHint, idempotentHint), the description adds substantial context: the exact output structure, refusal reason codes, the guarantee to use only tool-result content, and the extra LLM call cost. It does not contradict 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 dense but every sentence earns its place: mode, routing, output, use cases, cost. It is front-loaded with the core purpose and avoids fluff.

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

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

Given the tool's complexity and no output schema, the description fully compensates by specifying the return shape, refusal reasons, usage scenarios, and alternatives. It provides a complete end-to-end understanding.

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

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

The schema has 100% coverage with detailed descriptions for the required parameter and all six aliases. The description adds no extra parameter-specific information, so it meets the baseline without exceeding it.

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

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

The description clearly specifies the tool as a hallucination-resistant answer mode, naming the verb (answer) and the resource (Pipeworx data sources). It distinguishes itself from the sibling ask_pipeworx by emphasizing evidence-based extraction and explicit refusal behavior.

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

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

It explicitly states when to use this tool (high-stakes answers, quoted/cited/acted on, no invention of facts) and when not to (casual lookups). It also names the preferred alternative (ask_pipeworx) and explains the cost tradeoff.

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 extensively adds behavioral context: low-confidence short-circuits, market closed handling, resolution-rule risk, parent event extraction, news fallback fields, and tradeability warnings. 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 comprehensive but quite lengthy; it front-loads the purpose but then dives into dense detail (classifiers, fan-out examples, response shapes, resolver contract). While every sentence adds value, the structure could be more streamlined for quick scanning. A mid-range score is appropriate.

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

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

Given the tool's complexity (no output schema, 3 params with nuances), the description thoroughly covers input formats, behavioral modes, safety checks, resolution logic, and response structure. It compensates for the missing output schema with detailed response shape descriptions. An agent has sufficient context to use the tool correctly.

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

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

Schema coverage is 100% (all 3 parameters described). The description adds significant value: explaining market accepts slug/URL/question text, depth options (quick/thorough) with defaults, include_raw and its use cases. This goes beyond the schema's basic enumerations and 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 researches a Polymarket bet by pulling Pipeworx data, with specific verb-resource combinations. It distinguishes from siblings (e.g., compare_entities, polymarket_edges) by focusing on betting research with data fan-out.

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

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

The description provides clear usage examples ('should I bet on X', etc.) and lists classifiers and fan-out examples, implying when to use. However, it lacks explicit when-not-to-use guidance or direct comparisons with sibling tools like polymarket_edges or validate_claim.

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, non-destructive. Description adds off-calendar handling, sorting by metric, citation URIs, and replaces multiple lookups. No contradictions.

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

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

Front-loaded with trigger queries and preference rule. Each sentence adds value. Slightly verbose but well-structured and informative.

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

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

No output schema but description explains return format (paired data + citation URIs). Covers main use cases and behavior adequately.

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. Description adds detailed behavior per enum value and example formats for values, exceeding 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 side-by-side comparison of 2-5 companies/drugs with specific trigger phrases. Distinguishes from sequential lookups and specifies data sources per type.

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 preference over sequential lookups is stated. Example queries guide when to use. Missing explicit exclusions but context with sibling tools provides clarity.

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 declaring readOnly/openWorld, the description adds extensive behavioral context: account requirements, depth-specific hop and gap-recovery behavior, 'never invented' grounding, contradiction[] output, stable pipeworx:// citations, semantic excerpting, and expected latency. This far exceeds the annotation baseline.

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 very long; every section packs useful information (account, alternatives, depth, citations, latency) and is logically ordered. Slightly over-detailed, which costs a point, but nothing is redundant 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?

With no output schema, the description compensates by fully describing the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]). It also covers prerequisites, alternatives, depth levels, and performance expectations, making it a complete usage guide.

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

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

Schema already covers 100% of the two parameters. The description still adds value by explaining depth's 'standard' vs 'thorough' semantics (gap recovery, contradiction scans, paid plan) and clarifying that the question can be 'broad/multi-part' — details 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 states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, distinguishing it from open-web search and the single-lookup ask_pipeworx sibling. It specifies the resource and the action, making its purpose unambiguous.

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

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

Explicit guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' plus 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names ask_pipeworx as the fallback when not signed in, so when-to-use and alternatives are clearly stated.

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 mark the tool as read-only and idempotent. The description adds valuable behavioral details: returns top-N relevant tools with names, descriptions, full input schemas, and curated examples, and states results are 'ready to call directly, no second schema lookup needed'. This goes well beyond the annotations.

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

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

The description is relatively concise for the amount of information it conveys. It front-loads the purpose and use cases, then describes the output. A few extra words could be trimmed, but it remains efficient 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?

Despite lacking an output schema, the description fairly covers what the tool returns: names, descriptions, full schemas with examples. Given the parameter complexity (6 params, all documented) and the absence of output schema, the description provides sufficient context for an agent to understand the tool's behavior and results.

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

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

Schema coverage is 100%, so the description adds little beyond what the schema already provides for individual parameters. The description does not elaborate on parameter meanings or constraints beyond the schema descriptions, which is acceptable given the 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 uses a clear verb ('find') and resource ('tools'), and specifies numerous example domains (SEC filings, FDA drugs, etc.), making the purpose unmistakable. It also differentiates from sibling tools by positioning itself as a discovery/search tool to be used when browsing the tool set.

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 advises 'Call this FIRST when you have many tools available and want to see the option set', providing clear usage context. It does not explicitly list when not to use it or mention alternatives, but the guidance is strong enough for an agent.

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

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

The description adds significant behavioral context beyond the annotations: it fans out across multiple sources, details return fields, mentions patent sunset soft-fail, and explains fallback logic. No contradiction with annotations.

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

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

The description is long but well-structured, front-loading with examples. Every sentence adds value, though it could be trimmed slightly without losing information. Still highly 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 only 2 parameters and no output schema, the description thoroughly explains return fields, sources, limitations, and fallbacks. Nothing essential is missing.

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

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

Schema coverage is 100%, and the description adds meaning: type is 'company' only, value expects ticker or CIK, names not supported. This goes beyond the schema's basic type and enum constraints.

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

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

The description starts with explicit example queries and clearly states 'full cross-source profile of a US public company in ONE parallel call'. It lists the sources and returned fields, making the purpose unmistakable. It also distinguishes from chaining 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?

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and states 'names not supported (use resolve_entity first if you only have a name)', 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?

Annotations already declare destructive and idempotent behavior. Description adds 'sensitive data' context but lacks details on edge cases like key not found or return value. Acceptable but not exceptional.

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 purpose, no redundancy. 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?

Complete for a single-parameter destructive tool with good annotations. Includes purpose, usage guidelines, and pairing advice. No output schema needed.

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

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

Schema covers 100% of parameters with description 'Memory key to delete'. Description adds no new meaning beyond 'by key', so 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?

Clearly states the tool deletes a memory by key, using specific verb 'delete' and resource 'memory'. Distinguishes from siblings remember and recall.

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

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

Provides explicit when-to-use scenarios: stale context, task completion, clearing sensitive data. Names alternatives (remember, recall) and suggests pairing.

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, openWorld, idempotent, non-destructive. The description adds behavioral context by explaining the process: fetches the page, extracts title/description/key links, and emits standard markdown. It also mentions the output format (single text blob ready for site-root/llms.txt). 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 sentences, each serving a purpose: first sentence states the core action and why, second explains the process, third lists use cases. Front-loaded with the essential verb. No fluff.

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

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

With 2 parameters, no output schema, and rich annotations, the description fully covers what the tool does, how it works, and what the output is. It even suggests where to place the output (site-root/llms.txt), making it complete for an agent to use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no new meaning beyond what the schema already provides for both 'url' and 'max_links' parameters. The description repeats the schema's descriptions without elaboration.

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

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

The description clearly states the verb 'Generate', the resource 'llms.txt file', and the specific action of fetching, extracting, and emitting. It distinguishes this tool from siblings by focusing on generating llms.txt for a URL, which is distinct from other tools like scan_competitor_ai_presence or deep_research.

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 use cases: getting a client's site indexed, drafting for own project, auditing competitors. It does not mention when not to use or alternatives, but the guidance is clear and context-rich.

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, etc. Description adds specific return fields (id, type, params, timestamps, fire_count), providing useful behavioral detail 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 sentences, front-loaded with the action and output, with no wasted words. Efficient and clear.

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

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

Given no output schema, the description explains return fields and usage context. It fully covers agent needs for this simple read operation.

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 'include_inactive' with a clear description. The tool description does not add further parameter semantics beyond what the schema already provides.

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

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

Clearly states it lists the caller's active subscriptions and specifies return fields. Distinguishes from siblings like subscribe/unsubscribe by describing its role in reviewing current subscriptions.

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

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

Explicitly tells when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and alternatives.

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

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

Annotations are all false (not read-only, not open-world, not idempotent, not destructive), yet the description adds valuable behavioral context: anonymous filing returns a claim_token, rate limit of 5 per identifier per day, free and not counted against quota, and daily team review. These traits go far beyond what annotations convey and set clear expectations for the agent.

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 is front-loaded with the main purpose, then logically moves through triggers, exclusions, message guidelines, claim token behavior, and rate limits. No redundancy or fluff; length is justified by the richness of required context.

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

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

With no output schema, the description explicitly discloses the return behavior (claim_token for anonymous filing and how to use it to check resolution). It covers all usage contexts, exclusions, rate limiting, and quota impact, giving the agent a complete operational picture for a nuanced feedback tool with 4 parameters and nested 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 description coverage is 100% and each parameter already has detailed descriptions (e.g., claim_token explains the read-reply flow, message describes specificity and max length). The description reinforces claim_token usage and adds a crucial semantic cue: describe issues in terms of Pipeworx tools/packs, not end-user prompts. This one extra piece of guidance raises it above the 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 opens with a clear, specific directive: 'Tell the Pipeworx team something is broken, missing, or needs to exist' and lists the exact feedback types (bug, feature/data_gap, praise). It explicitly scopes to tools served by this Pipeworx connection, distinguishing it from other MCP servers and filling a unique niche among sibling tools. No other sibling provides a feedback channel, so the purpose is unambiguous.

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

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

Usage guidelines are explicit and comprehensive: it states when to use (bug, feature/data_gap, praise) and when not to use ('if the tool came from a different MCP server... file it with that server instead'). It also provides practical guidance on how to phrase feedback (describe in terms of Pipeworx tools/packs, do not paste the end-user's prompt), and explains the claim token flow. This fully satisfies the dimension.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context: data source (CF analytics-engine), privacy (no PII, just counts), and caching behavior (5min-1h). 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 a single paragraph with clear structure: output, use cases (numbered), and technical notes. It is informative without being excessively long, though could be slightly more terse.

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

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

For a simple read-only tool with one parameter, the description covers output (top tools, packs, volume), data source, privacy, and caching. No output schema exists, but the description sufficiently sets expectations for an AI agent.

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

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

Schema has 100% coverage with enum description. The description adds behavioral nuance: 'shorter windows surface what's hot right now; longer windows show steady-state demand,' which aids parameter selection beyond schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a specified window. It uses specific verbs and resource, and distinguishes from siblings like 'discover_tools' by focusing on trending 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 lists three explicit use cases and explains the difference between window choices. It does not provide when-not-to-use or alternatives, but the context is sufficient for an AI agent to select appropriately.

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

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

The description discloses extensive behavioral details beyond annotations: how it runs (walks child markets, computes partition checks), the semantic anchor (≥0.30 Jaccard similarity), partition filter (placeholder slugs), fill check against CLOB depth, and response structure. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false).

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 clear sections for each mode and additional features (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). It is front-loaded with the core purpose. While verbose, it earns its length due to the tool's complexity; minor redundancy could be trimmed but overall effective.

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

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

For a complex tool with no output schema, the description thoroughly covers input modes, internal logic, response fields (gap_pp, suggested_trade, etc.), fill check conditions, and fallback to fill_risk. It provides enough context for an AI agent to correctly invoke the tool and interpret results without ambiguity.

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

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

Schema coverage is 100% (both parameters described in schema). The description adds significant value beyond schema: explains the recommended usage for each parameter (event slug format, topic seed question), the algorithmic context (e.g., cross-event pairing logic), and hints about acceptance of full Polymarket URLs. This compensates for the lack of enums or nested objects.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three invocation modes (no args, event, topic) and differentiates each with concrete examples, distinguishing it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly states when to use each mode: call with NO args for trending scan, pass event for a specific market (recommended for known events), or topic for cross-event scanning. It also provides negative guidance (do not trade when realizable_edge_pp ≤ 0) and points to polymarket_fill_risk for custom sizing, offering clear decision paths.

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 confirm read-only, idempotent, non-destructive behavior, which the description complements with extensive behavioral details: caching (1h at KV level), model families, edge computation, response segments, diagnostics for empty segments, and the 24h-move warning. 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 thorough but verbose, spanning four paragraphs. It front-loads the main purpose but then dives into technical details that could be streamlined. Every sentence adds information, but the length may hinder quick understanding.

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 9 parameters, no output schema, and complex response structure, the description covers the response top-level fields (by_segment, fed_candidates, diagnostics), caching, and tradeable-edge knobs. It explains why segments might be empty. Slightly lacking explicit return shape, but the detailed listing of opportunity fields (edge_pp_net, kelly_fraction, etc.) compensates.

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 beyond schema descriptions by explaining how parameters affect results (e.g., min_partition_leg_kelly applies to per-leg Kelly inside partitions) and giving practical advice (e.g., slippage_pp default 0.3 with reasoning).

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This is a specific verb+resource combo, and the detailed explanation of model families and response segments distinguishes it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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 'Built for "what should I bet on today"' and explains the tradeable-edge knobs (min_liquidity, max_spread_pp) and their purpose. It also notes that Fed bets are excluded from ranking. However, it does not directly contrast with sibling tools or specify when not to use it.

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

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

The description adds value beyond annotations by detailing the snapshot source, potential data gaps, TTL, and response structure. It explains that snapshots are written on cache-miss, affecting completeness. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and query, then details response format and limits. It is dense but every sentence adds value; slightly long but 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?

Despite no output schema, the description fully details the response structure (tracked[], expired[], snapshot_dates[]) and important fields (trend, decay_pp_per_day, lifespan_days). It covers edge cases like gaps and TTL limits. Very complete.

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

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

Schema coverage is 100% with clear parameter descriptions. The description repeats some schema info but adds context about 'window' being a 'snapshot family' and relates to response dates. Minor added value; 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 it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge duration. It distinguishes from siblings like 'polymarket_edges' by focusing on history vs. current edges.

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

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

The description explains the tool answers 'how long has this edge existed and is it shrinking?' and provides context about when to use it (e.g., different trading decisions for fresh vs. old edges). It does not explicitly mention when not to use or list alternative tools, but the purpose is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and no destructiveness. The description adds behavioral detail: it walks the order-book ladder, returns fill details (top_of_book, vwap_fill_price, etc.), a verdict (clean|degraded|cannot_fill), and for baskets captures risks like forced_directional_risk. No contradiction with annotations; the description enriches understanding of the tool's operation.

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 fairly long but well-structured with capitalization for emphasis (REQUIRES, SINGLE-MARKET, BASKET) and clear separation of modes. Each sentence adds value, but some redundancy exists (e.g., repeating 'side' explanation). Overall it earns its length given tool 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?

Even without an output schema, the description lists all return fields for both modes (top_of_book, vwap_fill_price, etc.), explains verdict categories, and highlights critical risks like forced_directional_risk. This provides a complete mental model of the tool's output.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The description adds significant meaning: explains size_usd interpretation per mode (max spend vs target proceeds vs settlement notional), side defaults (auto for baskets based on partition sum), and the mutual exclusivity of market/event parameters. This goes well beyond the schema.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth, with two distinct modes (single-market and basket). It differentiates from siblings by explicitly advising use before acting on polymarket_arbitrage or polymarket_edges signals. The verb 'check' and resource 'CLOB order-book depth' are specific and unambiguous.

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

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

The description explicitly states requirements (REQUIRES one of market or event) and provides clear usage context: use before acting on arbitrage or edge signals for trades above ~$500. It also warns about partial basket fills converting arbitrage into unhedged directional positions, which is critical for correct tool 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses extensive behavioral traits: the two operation modes, response structure including leg-by-leg prices and matched spreads, safety fields with specific conditions (matched_pairs:0 cases), temporal alignment details, and skipped cross-type/subtype counters. This far exceeds annotation coverage with no contradictions.

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

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

The description is dense but well-structured with clear sections (modes, response, safety fields). Every sentence adds value, though length could be slightly reduced by using bullet points or shorter phrases. Overall, it earns its length for the complexity of the tool.

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

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

The tool has no output schema, so the description adequately covers return values: leg-by-leg prices, matched spreads with top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. Combined with full parameter documentation, the description leaves no gaps for agent understanding.

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

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

With 100% schema description coverage, the description adds significant meaning: it lists all 10 topic shortcuts, provides example values for explicit tickers, and explains the interaction between topic and explicit parameters (overriding behavior). This context greatly helps the agent understand parameter usage beyond the schema itself.

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

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

The description clearly defines the tool's purpose as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the verb 'compute spread' and the resource 'same resolving question', distinguishing it from sibling tools like polymarket_arbitrage which likely focus on other arbitrage aspects.

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 outlines two usage modes (topic shortcuts vs explicit tickers) and provides detailed interpretation guidance for response fields like compatibility_warning and temporal_alignment. It warns that pre-mapped topics often return warnings, helping agents set expectations. However, it does not explicitly contrast with alternatives or state when not to use this tool.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping details (anonymous IP, BYO key hash, account ID) and pairing context, but these are not critical beyond what annotations convey.

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

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

The description is three sentences, front-loaded with the main purpose. Every sentence adds value with zero waste.

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

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

For a simple read-only retrieval tool with one optional parameter and no output schema, the description covers purpose, behavior, and usage comprehensively without needing further detail.

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

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

Schema coverage is 100% with the 'key' parameter well-described. The description adds that omitting key lists all keys, which is already in the schema property description. Baseline 3 is appropriate.

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

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

The description clearly states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This provides a specific verb and resource, and distinguishes from sibling tools remember and forget.

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

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

The description explains when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping and pairing with remember/forget, but does not explicitly state when not to use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that each alert carries source, citation_uri, and raw payload, and explains that setting mark_read:true flags events as read so the next call shows only newer ones. This provides specific behavioral context beyond the annotations.

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

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

The description is a single paragraph of five sentences, with the purpose stated upfront. Every sentence provides necessary detail without repetition or fluff. The structure is efficient and front-loaded.

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

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

The description covers the core return fields (source, citation_uri, raw payload), filtering options, and the mark_read side effect. It also mentions the external URL as an alternative. While it lacks explicit pagination details beyond the limit parameter, the description is adequate for a read-only tool with annotations covering safety.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving an example filter ('sec_8k'), specifying the ISO timestamp format for 'since', and explaining the effect of 'mark_read:true'. This enhances understanding 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 opening clause 'Pull fired events from your subscription feed' immediately states the action (pull) and resource (fired events from subscription feed). It further specifies 'returns the most recent alerts' and mentions filtering, making the scope clear. Among sibling tools, none directly duplicate this functionality.

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 that 'Polls work fine' and provides an external URL as an alternative for scripts/dashboards, giving some context. However, it does not explicitly state when to use this tool over sibling tools like 'list_subscriptions' or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds valuable context: fans out to multiple sources, fallback logic, soft-fail for USPTO, and return format (structured changes with citation URIs). No contradictions.

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

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

Description is somewhat long but each sentence adds value. Front-loaded with example queries. Could be slightly more structured (e.g., bullet list of sources), but no filler words. Effective for an agent.

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

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

No output schema, so description explains return values: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. Covers complex multi-source behavior, fallbacks, and soft-fail. Completely adequate for agent decision-making.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains `type` enum limitation ('Only "company" supported today'), `since` format variants and a recommended value, and that `value` accepts ticker or CIK. Provides practical usage context beyond schema.

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

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

The description clearly states the tool returns a change feed for a company, covering SEC filings, news, and patents. It uses specific verbs and resources ('change feed', 'fans out to SEC EDGAR...') and distinguishes itself from the sibling `entity_profile` by contrasting static profile vs. windowed changes.

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

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

Explicit guidance: 'Use entity_profile instead when you want the static profile...' and recommends typical `since` values ('Use "30d" or "1m" for typical monitoring'). Also describes fallback behavior (GDELT→GNews) and soft-fail for USPTO due to API sunset.

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 idempotentHint=true and non-destructive. Description adds valuable context: memory scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. 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 sentences, no waste. First sentence establishes purpose, second provides usage guidance, third adds persistence behavior. Front-loaded and 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 simple key-value store with no output schema, the description covers all needed aspects: purpose, when to use, persistence behavior, and relation to siblings. Complete for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions for both key and value parameters. The tool description restates purpose but doesn't add format details beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states 'Save data the agent will need to reuse later' specifying action (save), resource (data), and scope (key-value pair, cross-session). Distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward' and mentions pairing with recall and forget for retrieval/deletion. Also explains scoping and persistence duration for authenticated vs anonymous users.

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: labels identifiers with source, explicitly lists unresolved identifiers, and describes graceful degradation when GLEIF/OpenFIGI are unavailable. This provides valuable insight into internal behavior 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 well-structured and front-loaded with the intended use case, but somewhat lengthy. The multiple example phrases at the start are slightly repetitive, though they reinforce usage. Overall, it earns its length given the tool's complexity.

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

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

Despite lacking an output schema, the description adequately explains the return expectations: canonical identifiers per type, labeling with sources, and handling of unresolved entries. It also covers failure modes and internal cascading. This is complete for an agent to use 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 enriches the schema by explaining each supported type in detail, giving concrete examples for both parameters, and clarifying what value forms are accepted for company and drug. This goes far 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 resolves a user-spoken name to canonical/official identifiers, with specific verb+resource and examples. It distinguishes from siblings like entity_profile by focusing on lookup of IDs rather than profiles or comparisons.

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 FIRST whenever you have a name but need an ID,' providing a clear directive for when to use. It also notes it replaces 2-3 manual lookups, indicating preference over alternative multi-step processes.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive. The description adds behavioral details: how it probes (with ai_visibility_check), the ranking process, and the returned data fields (score, confidence, signal density). 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 three sentences, front-loaded with the main action, and each sentence serves a purpose. No filler or redundancy.

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

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

Given the tool's complexity (multi-entity comparison, no output schema), the description covers purpose, behavior, and output fields adequately. However, it lacks details on error cases, limits on entity count (implicit in schema: 2-8 but not restated), or handling of missing data.

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% description coverage, but the description adds important context: that the first entity is treated as the 'subject' for narrative, and clarifies default model behavior ('Omit for just workers-ai'). This adds meaning beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities, explicitly mentioning it probes each with ai_visibility_check and ranks results. It distinguishes itself from the sibling ai_visibility_check by describing multi-entity comparison.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question, implying when to use it. However, it does not explicitly state when not to use it or name alternatives like ai_visibility_check for single entity checks.

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. Description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement delay, and the sources_failed field. No contradiction with annotations.

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

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

Description is detailed and front-loaded with purpose, but slightly long (4 sentences). Every sentence adds value, so minor deduction for brevity.

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

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

Tool is complex (composite, multiple sources). Description covers inputs, outputs (summary block), behavior (partial failures), ecosystem scope. No output schema, so description adequately explains return format.

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

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

Schema coverage is 100% with parameter descriptions. Description adds context about default version behavior and scoped packages, but schema already covers basic info. Baseline 3, extra value for default behavior explanation.

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's a composite check for 'should I add this npm package', covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by specifying NPM ecosystem only, with other ecosystems falling under deps.dev:version.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also mentions what it's NOT for (other ecosystems) and provides alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds beyond that: embedding model (BGE-base-en), chunking (500-char overlapping windows), character limit (200K with truncation flag), and output includes offsets and similarity scores. No contradictions.

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

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

Description is front-loaded with purpose, then examples, usage guidance, and technical details. Each sentence adds value, but could be slightly tighter without losing information.

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

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

Given 3 parameters, no output schema, and comprehensive annotations, the description covers purpose, usage, parameter details, technical implementation, and edge cases (truncation). It is fully informative for an AI agent.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds value by clarifying text max length (200K chars), providing natural-language query examples, and stating limit default (5).

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

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

The description uses a specific verb ('semantic search inside') and resource ('fetched record'), with concrete examples (SEC 10-K, article) and clearly distinguishes from sibling ask_pipeworx_grounded by explaining how they pair together.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Mentions pairing with ask_pipeworx_grounded, but does not explicitly exclude alternatives or mention when not to use it.

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

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

The description explains that each call creates a new subscription and returns an id, but the idempotentHint annotation suggests it should be safe to retry without creating duplicates, which is contradictory. Otherwise, the description provides good context on authentication, delivery channels, rate limits (10/day for SMS), and verification requirements for phone numbers. Annotations already indicate it is not read-only or destructive, so the description adds moderate 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 detailed and front-loaded with the main purpose. Every sentence provides useful information, though it could be slightly more concise by grouping related details. Overall, it is well-structured for an AI agent to parse.

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

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

The description covers all relevant aspects: what the tool does, prerequisites, supported types with config, delivery options, rate limits, verification steps, and what the return value is. Given the complexity of the tool and the absence of an output schema, the description is complete and leaves no major gaps.

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

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

The schema has 100% description coverage, and the tool description significantly enhances the schema's meaning by providing examples for each subscription type's params object, explaining delivery channel options with details like signing for webhooks, and documenting constraints such as the 10/day SMS cap. The description adds critical context not present in the schema alone.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, with a specific verb and resource. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts which serve different purposes.

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

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

The description specifies that a Pipeworx OAuth account is required, excluding anonymous and BYO users. It also provides guidance on when to use this tool versus pulling data via recent_alerts or the GET endpoint, and lists supported subscription types with examples. However, it does not explicitly state when to choose this tool over alternatives like polymarket_edge_tracker or other data-fetching tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral context about the output (returns category-bucketed questions with exact tools and argument shapes drawn from live catalog) which is not in annotations, enhancing transparency.

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

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

The description is well-structured with front-loaded example queries, concise sentences, and no fluff. Every sentence adds value: purpose, output description, usage instructions, and sibling differentiation.

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 (0 required params, no output schema), the description is remarkably complete: it explains purpose, when to use, how to invoke, what the output contains, and even lists the categories. Nothing essential is missing.

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

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

Schema covers the topic parameter with 100% description, but the description adds usage examples ('e.g. finance, pharma, betting') and clarifies behavior when omitted. This goes beyond the schema's baseline, warranting 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 that the tool returns category-bucketed example questions with tool+argument shapes, and positions it as the onboarding entry point. It distinguishes itself from siblings by explicitly recommending to use this FIRST when the agent doesn't know what Pipeworx can do.

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

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

The description provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools...' and explains both the no-argument and topic-filtered invocations.

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

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

Discloses ownership enforcement and deactivation (not deletion) beyond annotations. Aligns with non-destructive and idempotent hints. No contradictions.

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

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

Two concise sentences, front-loaded with action, no wasted words. Efficiently conveys purpose and key behaviors.

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

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

Given one parameter, no output schema, and rich annotations, the description adequately covers ownership, idempotency, soft-delete, and impact on historical data, making it 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 covers the single parameter fully (100% coverage). Description adds that the id comes from subscribe, but provides no additional syntax or format details, meeting 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 verb 'Cancel' and resource 'subscription', and distinguishes from siblings like subscribe and list_subscriptions by specifying ownership enforcement and soft-delete behavior.

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 (cancel own subscriptions) and implies not for others. Mentions historical events remain via recent_alerts, guiding tool selection. Does not explicitly name alternatives but context suffices.

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 substantial behavioral context beyond the annotations: the two routing paths (SEC EDGAR/XBRL vs. grounded pipeline), the full verdict set, the critical distinction between could_not_verify (a failed check, not evidence) and unsupported (no source found), and the inclusion of pipeworx:// citations. 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 longer than average but front-loaded with the purpose and each sentence earns its place: examples, usage, mechanism, return semantics, and a caller warning. It is well-structured despite its length, though it could be tightened slightly by trimming redundant phrasing.

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

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

Given the tool's complexity (two routing paths, six verdicts, failure semantics), the description is remarkably complete. It covers return format, source handling, and the special meanings of could_not_verify and unsupported, leaving no major gaps even without an output schema.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions for claim and tolerance_pct, so the baseline is 3. The description adds minimal parameter-specific detail (e.g., exact percent-delta math) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources. It includes specific example query patterns ("Is it true that...", "fact check") and distinguishes between financial claims and all other factual claims, making its scope unambiguous relative to sibling tools like ask_pipeworx or deep_research.

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,' providing clear context. It also mentions that the tool replaces 4–6 sequential calls, implying it is the preferred single-call approach. However, it does not name sibling alternatives or describe when not to use it, so it stops short of full when/when-not guidance.

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