Currents

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds value by detailing the return structure (per-model {score, confidence, signals, raw_response} + combined view) and explaining the free default model and the pass-through API key mechanism. No contradictions with annotations.

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

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

The description is concise (3-4 sentences) with the main purpose front-loaded. Every sentence adds essential information: what it does, how it works, what it returns, and usage context. There is no fluff or repetition.

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

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

Given no output schema, the description adequately explains the return format. It covers all parameters, the default model, optional API key, and use cases. For a tool with moderate complexity, the description is sufficiently complete for an agent to understand how to invoke it correctly.

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

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

All 4 parameters have schema descriptions (100% coverage), but the description goes beyond by providing examples for 'entity', clarifying the 'models' list values and their prerequisites, and explaining the 'context' disambiguation purpose. This adds meaningful context beyond the schema.

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

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

The description uses a specific verb ("Probe") and resource ("LLMs for what they know about a business/brand/product/topic") and clearly states the output (score 0-100). It distinguishes from siblings by focusing on visibility scoring across models, while similar tools like 'scan_competitor_ai_presence' likely have a different scope.

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 tells when to use the tool ("AI-marketing audits, pre-launch brand checks, competitive monitoring") and explains the default model and the optional Anthropic probe with its API key requirement. However, it does not explicitly mention when not to use it or directly compare to sibling tools, leaving some implicit guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds valuable behavioral context: routes to 3,745 tools across 884 sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. No contradictions.

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

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

Description is front-loaded with the critical preference directive and domain list. Some redundancy in listing aliases (already in schema) could be trimmed, but overall structure is clear 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?

Given the tool's complexity and lack of output schema, the description adequately covers purpose, usage scope, behavioral traits, and examples. It mentions structured answers and citations, partially compensating for no 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?

Schema coverage is 100% with detailed descriptions and aliases for the single required parameter. Description adds no new parameter-level information beyond the schema, aligning with the baseline score for high coverage.

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

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

Description uses specific verb 'ask' and clearly defines the resource ('Pipeworx') with extensive context of domains. It distinguishes from web search and provides concrete examples, making the purpose unmistakable.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' for a wide range of factual queries and lists specific query patterns like 'what is', 'look up', 'find'. Includes examples, providing clear when-to-use guidance.

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

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

The description adds significant behavioral context beyond annotations: it details the refusal reasons, the fact that answers are extracted only from tool results, and the cost trade-off. No contradictions with annotations.

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

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

The description is concise yet comprehensive, front-loading the key purpose and returning format, then detailing usage. Every sentence adds value without redundancy.

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

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

Given the complexity (multi-tool routing, extraction, refusal handling) and absence of output schema, the description is remarkably complete, covering use cases, return fields, refusal reasons, and cost implications.

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 params are aliases for question). The description confirms natural language input and lists aliases, but adds minimal additional semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'hallucination-resistant answer mode for high-stakes reads.' It explicitly distinguishes this from the sibling ask_pipeworx by explaining the additional extraction and refusal mechanisms.

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 whenever an answer will be quoted, cited, or acted on...' and advises preferring ask_pipeworx for casual lookups due to extra cost. This covers when to use and when not to.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral detail beyond annotations: it explains resolver contract (low-confidence match short-circuit, market_closed_or_inactive status), liquidity warnings, resolution-rule risk parsing, parent event extraction, and news fallback behavior. No contradictions with annotations.

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

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

The description is lengthy but well-structured, starting with purpose, then classifiers, fan-out examples, response shapes, and edge cases. Every sentence adds information, but some parts could be more concise (e.g., the RESOLVER CONTRACT section is detailed). Overall, it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (multiple classifiers, fan-outs, response fields, edge cases), the description is very complete. It covers safety, market status, liquidity, resolution rules, parent events, news fallback, and examples. Since there is no output schema, the description explains return values in sufficient detail (result.market, result.analysis, result.evidence, etc.).

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 adds value by explaining the semantics: examples of valid market_inputs (slug, URL, question text), the meaning of 'quick' vs 'thorough' depth (2-3 vs full fan-out), and the effect of include_raw (summarized vs full payloads). This clarifies usage beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), the resource (Polymarket bet), and provides explicit use cases like 'should I bet on X'. While it doesn't explicitly distinguish from sibling tools, the detailed scope makes it clear this is a comprehensive research tool.

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

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

The description gives explicit usage scenarios (e.g., 'should I bet on X', 'what does the data say about Y') and provides examples of fan-outs. It also mentions a 'depth' parameter for quick vs thorough, implying gradations. However, it does not explicitly state when to avoid using this tool or compare it to alternative sibling tools like polymarket_edges.

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

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

Adds detailed behavior beyond annotations: describes data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), specific metrics retrieved, handling of off-calendar fiscal years, sorted results, and citation URIs. No contradiction with annotations.

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

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

The description is clear and front-loaded with key usage guidance. It is informative but slightly dense; a more structured format (e.g., bullets) could improve readability, but it remains efficient.

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

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

Covers purpose, usage, data sources, output format, and citations. Lacks discussion of error cases or edge conditions, but given the absent output schema, it provides sufficient context 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?

Schema coverage is 100%, and description adds examples (tickers, drug names) and explains how each type is used. Provides context on what data each parameter returns, enhancing the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It includes trigger phrases and distinguishes from siblings like entity_profile by emphasizing preference over sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides example queries and context, making it clear when to use this tool versus alternatives.

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

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

Annotations already indicate safe, idempotent, open-world behavior. Description adds significant detail: decomposition into sub-questions, parallel tool usage, evidence extraction with confidence/source/citation, explicit gaps, and 15-60s latency. 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 front-loaded with purpose and mechanism, each sentence adds value. Slightly verbose but all information is useful. Could tighten slightly, but overall well-structured.

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

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

For a complex tool with no output schema, description covers purpose, mechanism, inputs, output format (findings packet with evidence/gaps), usage guidance, and prerequisites. Minor gap: could explicitly state exact output structure, but sufficient.

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 describing both parameters. Description adds context that depth 'thorough' requires a paid plan, which is not in schema. Otherwise, description doesn't add beyond schema, so baseline 3 is elevated to 4 for the extra context.

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

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

Description clearly states 'Grounded multi-source research in ONE call' and explains decomposition, parallel routing, and extraction. It distinguishes from sibling tool ask_pipeworx for single lookups, providing specificity and differentiation.

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

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

Explicitly advises use for broad/multi-part questions and directs single lookups to ask_pipeworx. Also mentions account requirement and paid plan for thorough depth, giving clear when-to-use and when-not-to guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by stating that results include full input schemas with curated examples and are ready to call without second lookup, which is important behavioral context beyond annotations.

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

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

The description is front-loaded with purpose, includes inline examples, and delivers usage guidance in a compact form. Every sentence adds value without being overly verbose, though it could be slightly more concise.

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

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

For a tool discovery function with high schema coverage and no output schema, the description adequately explains what returns (top-N tools with schemas). It mentions the limit parameter but could note sorting or pagination behavior.

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

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

Schema coverage is 100% with all parameters described, so baseline is 3. The description mentions that query accepts multiple aliases (task, q, description, search), but this is already reflected in the schema. No additional parameter semantics are provided.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly states the verb ('find') and resource ('tools'). It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools, which are task-specific rather than discovery-oriented.

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 'Call this FIRST when you have many tools available and want to see the option set,' providing clear usage context. While it doesn't explicitly list when not to use, the guidance is strong enough to differentiate from direct-answer siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: parallel call, sources fanned out, specific returned fields, USPTO soft-fail after May 2025, and note about names not supported. Highly transparent, though rate limits or pagination are not mentioned.

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 example queries and a strong statement of intent. Every sentence adds information (sources, output fields, limitations). It is slightly long but justified by the tool's complexity. Could be trimmed slightly, but overall well-structured.

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

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

Given the tool's complexity (multi-source, many output fields) and the absence of an output schema, the description provides a complete overview: lists what is returned (CIK, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It acknowledges the USPTO sunset and doesn't need to explain return values further. Lacks explicit error handling, but sufficient for agent 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% (both parameters described). The description adds real value beyond the schema by providing examples ('AAPL', '0000320193'), clarifying usage (ticker or zero-padded CIK), and reiterating the name constraint. This helps the agent understand parameter semantics more deeply.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call'. It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and uses explicit verb+resource ('get profile'). It distinguishes from sibling tools like resolve_entity, compare_entities, and search_news by setting expectations.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing a clear when-to-use. Also states when-not-to-use: 'names not supported (use resolve_entity first if you only have a name)', guiding alternative 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?

Aligns with annotations (destructiveHint=true) and adds behavioral context about data sensitivity, though annotations already cover safety profile.

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 with front-loaded action and usage guidance, no wasted words.

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

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

Given simple schema (1 param, no output schema), description covers purpose, usage, and sibling relationships completely.

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

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

Schema provides full parameter description ('Memory key to delete'); description adds no extra semantics beyond what schema already conveys.

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

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

The description clearly states the action ('delete a previously stored memory by key') and explicitly names sibling tools for distinction.

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 done, clear sensitive data) and references related tools (remember, recall).

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 this is a safe, read-only, idempotent operation. The description adds value by explaining the exact output format (standard llms.txt markdown) and the intended deployment location (site-root/llms.txt), which goes beyond the annotations. No contradiction detected.

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

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

The description is two sentences, front-loads the primary action and result, and contains no unnecessary words. Every sentence adds value: the first defines the tool, the second gives context and use cases.

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 low complexity, no output schema, and complete parameter coverage, the description sufficiently explains inputs and outputs. It could mention handling of errors or timeouts, but that is not essential for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it lists what the tool extracts but does not detail parameter syntax or format. The 'max_links' parameter behavior is sufficiently described in the schema.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file') and clearly states what the tool does: fetches a URL, extracts metadata, and emits standard markdown format. It distinguishes itself from sibling tools by its unique output purpose, which no other tool in the list shares.

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

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

The description provides explicit use cases (client indexing, drafting, auditing competitors) but does not mention when not to use it or offer alternatives. The sibling list includes 'ai_visibility_check', which could be related but is not directly compared, so the guidance is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description adds moderate value by mentioning the source (70k+ sources) and filtering capabilities, but does not disclose any additional behavioral traits.

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 plus example: concise, front-loaded, every sentence adds value with no redundancy.

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

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

The description covers purpose, filters, and source, but does not explain return format or pagination. Given annotations and simplicity, it is mostly complete.

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

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

Schema coverage is 100%, so parameter descriptions already exist. The description adds an example call and mentions optional API key, but does not significantly enhance 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 retrieves recent global news articles from Currents, specifying verb and resource. It distinguishes from search_news by focusing on 'most recent', but does not explicitly differentiate from siblings like search_news.

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

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

The description implies usage for recent news with filtering options and provides an example, but lacks explicit guidance on when to use this tool versus alternatives like search_news or list_categories.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive nature. The description adds an example but no further behavioral context beyond what annotations provide.

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

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

The description is extremely concise: one sentence with a clear verb and resource, plus a minimal example. No wasted words.

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

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

For a simple listing tool with no output schema, the description is complete. It states the purpose and gives an example, leaving no gaps for the agent.

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

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

The input schema has 100% coverage with description for the single optional parameter. The tool description does not add any additional meaning beyond the schema's own description.

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

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

The description explicitly states the action ('List') and the resource ('news category labels supported by Currents'), with examples like technology, business. It clearly distinguishes from sibling tools like search_news or latest_news.

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

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

The description implies usage for obtaining supported categories before querying news. It provides an example call but does not explicitly exclude scenarios or name alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it returns active subscriptions by default and mentions the include_inactive parameter, which adds behavioral context beyond annotations.

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

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

Two tight sentences: first states purpose and return fields, second gives usage guidance. No wasted words.

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

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

For a simple tool with no output schema, the description fully covers the return fields and parameter behavior. Usage guidance completes the context.

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

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

Schema coverage is 100% with one boolean parameter. The description implies the default behavior (active only) and the purpose of the parameter, adding value beyond the schema's description.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description advises using this tool to review monitored subscriptions before adding more or to find an id to cancel, providing clear context for when 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?

Beyond annotations, it discloses rate limiting (5 per identifier per day), that feedback is free and doesn't count against tool-call quota, and that the team reads digests daily. 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?

Three front-loaded sentences with no wasted words. Each sentence provides distinct value: purpose, usage guidance, and behavioral notes.

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?

Fully covers all aspects for a feedback tool: what to send, how to structure it, rate limits, and impact. No output schema needed; tool is complete and unambiguous.

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

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

100% schema coverage, so baseline 3. Description adds value by advising to describe issues in terms of Pipeworx tools/packs and not to paste user prompts, which aids correct param usage.

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

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

The description clearly states the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. It distinguishes from siblings by being the sole feedback mechanism.

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

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

Explicitly describes when to use: for bugs, missing features, data gaps, or praise. Also specifies what not to do (don't paste user prompts). Gives context on rate limits and free status.

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

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

Description adds value beyond annotations: explains data source (CF analytics-engine), no PII, data structure (pack, tool, count), and caching (5min-1h). 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?

Concise single paragraph with bullet-like usage list. Front-loaded with purpose. No redundant sentences.

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

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

Covers return content, caching, privacy, use cases. Lacks explicit response format (JSON structure) but sufficient for a simple list. With no output schema, description does enough.

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

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

Schema coverage is 100%, description adds context: shorter windows for hot trends, longer for steady-state. Provides pragmatic guidance beyond enum list.

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

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

Description clearly states it returns top tools, packs, and call volume over a window. Verb 'returns' and resource 'trending data' are specific. Distinguishes from siblings like 'discover_tools' by focusing on trends and call volume.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, and alignment assessment. Does not mention when not to use or alternatives, but context is clear enough.

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

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

Annotations indicate read-only, open-world, and idempotent behavior. The description adds extensive behavioral context beyond annotations: computation methods, semantic anchor (Jaccard similarity), partition filter, fill check against live depth. No contradictions with annotations.

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

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

The description is long but every sentence adds value. It uses clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for structure. The requirement is front-loaded, and no word is wasted.

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

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

Despite no output schema, the description explains the response structure (opportunities[], partition_check, fill_check fields). It covers edge cases (no args failure, low similarity, placeholder filters) and references sibling tools for custom sizing. The tool is complex, yet the description feels complete.

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

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

Schema coverage is 100% but descriptions of event and topic are minimal. The description significantly enriches parameter meaning by explaining expected formats (slug or URL), mode behavior (single-event vs cross-event), and constraints (REQUIRES one of them).

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

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

The description explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks. It distinguishes two modes (event and topic) and is clear about what it does, differentiating from sibling tools like polymarket_edges.

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

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

The description explicitly requires one of `event` or `topic`, warns that calling with no args fails, and provides clear guidance on when to use each mode: event for specific markets, topic for cross-event scanning. It also includes fill check advice on when not to trade.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context: it explains the caching policy ('Cached 1h at the KV level'), the three response segments with detailed model families, and the diagnostics structure. This goes beyond annotations without contradicting them.

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

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

The description is overly long and dense, containing extensive technical detail about model families and filtering logic. While the information is valuable, it could be restructured (e.g., bullet points) and shortened without losing critical content. The opening sentence is clear, but the rest is verbose.

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

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

Given the complexity of the tool and the absence of an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and the fields in each opportunity. It covers edge calculation, Kelly sizing, and tradeable-edge knobs. A minor gap is the exact JSON format, but the description is largely complete.

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

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

Schema coverage is 100%, so the schema already documents all 9 parameters. The description adds high-level context for some parameters (e.g., 'tradeable-edge knobs'), but does not provide significantly deeper meaning beyond what is in the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings like polymarket_arbitrage by focusing on edge opportunities derived from Pipeworx data, not just arbitrage.

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

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

The description explicitly says 'Built for "what should I bet on today"' and mentions agents discover opportunities without paging hundreds of markets, providing clear context. However, it does not explicitly contrast with siblings or state when not to use this tool, which would improve 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?

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable behavioral details: history depth bounded by 60-day TTL, snapshot gaps meaning no scan that day, decay computed from daily closes not intraday. This fully discloses important behavioral traits 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 well-structured: purpose statement, high-level question, parameters, response breakdown, and limitations. It is front-loaded and every sentence adds value. Slightly verbose but still concise for the information conveyed.

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

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

Without an output schema, the description thoroughly explains the return structure (tracked, expired, snapshot_dates) and field meanings. It also covers limitations (TTL, intraday vs. daily). Given the tool's complexity and lack of output schema, the description is complete.

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

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

Schema coverage is 100% with adequate descriptions. The description adds defaults and context (e.g., days default 14, max 30; window default '1wk') and explains how parameters affect output (e.g., snapshot_dates). This adds meaningful value beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling 'polymarket_edges' (which likely focuses on current edges) by emphasizing historical analysis.

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

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

The description provides clear context on when to use the tool (to assess edge age and decay), contrasting fresh vs. old edges. However, it does not explicitly mention when not to use it or directly compare with sibling tools like 'polymarket_edges', though the context implies the distinction.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint=false. The description adds further detail: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict'. It also warns about thin books and partial fills, adding context beyond annotations.

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

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

The description is detailed and well-structured, using caps and bullet-like formatting to improve readability. Each sentence is informative, though slightly long; however the complexity justifies the length. Front-loaded with core purpose.

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

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

Given the tool's complexity (two modes, multiple return fields, warnings), the description covers all necessary aspects: input parameters, mode behavior, return values, usage context, and risks. No output schema exists, so returns are fully explained.

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

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

Schema description coverage is 100%, baseline 3, but description adds substantial meaning: explains mode-dependent interpretation of side (auto-detect for basket), size_usd (max spend vs target proceeds for single, settlement notional for basket), and clamp range. This significantly enhances understanding beyond schema.

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

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

The description clearly states the tool checks 'Realizable-vs-theoretical edge against live CLOB order-book depth'. It distinguishes two modes (single-market and basket) and explicitly contrasts with siblings like polymarket_arbitrage and polymarket_edges, saying to use this before acting on their signals.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills cause directional risk) and prerequisites (requires market or event).

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 and idempotent behavior. The description adds substantial behavioral context: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and counters for skipped cross-type/subtype comparisons. This goes well beyond the annotations and gives the agent a clear model of the tool's safety 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 thorough but somewhat verbose. It uses multiple paragraphs and includes some redundancy (e.g., 'pre-mapped ≠ tradeable' stated twice in spirit). While front-loaded with the core purpose, the length could be trimmed without losing key information.

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

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

Despite lacking an output schema, the description fully documents the response structure: leg-by-leg prices, spread array, top_spreads_pp, and safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers all parameter modes and explains how to interpret results, making the tool complete for the agent.

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

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

Schema already describes all 3 parameters with 100% coverage. The description adds value by explaining the 'topic' parameter values (list of 10 shortcuts) and the override behavior of explicit parameters. It clarifies that topic auto-fetches matching events, and explicit parameters override the mapped side.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on spread across venues rather than within-venue arbitrage, and describes two specific modes (topic and explicit pairing).

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

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

The description provides explicit guidance on when to use each mode (topic shortcuts vs. explicit pairs) and warns that pre-mapped topics may not be tradeable due to compatibility issues. It implicitly tells when not to use (when compatibility warning indicates mismatched bet shapes or semantic difference). However, it does not explicitly compare to alternative tools or state when to prefer another tool.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's main contribution is the scoping detail (per identifier) and the listing behavior when key is omitted. This adds meaningful context beyond annotations.

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

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

Three sentences, front-loaded with the essential action, no fluff. Every sentence serves a purpose: core action, use cases, and pairing with siblings.

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

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

Despite lacking an output schema, the description fully explains input behavior (retrieve or list), output nature (value or keys), and scoping. No gaps for this simple tool.

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

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

Schema coverage is 100% and already explains the parameter's behavior (omit to list all keys). The description reinforces this with practical use cases, adding marginal value.

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

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

The description clearly states the core action: retrieve a saved value or list all keys. It distinguishes itself from siblings (remember, forget) by naming them and contrasting their functions.

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

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

Explicitly explains when to use (look up stored context) and how it fits with remember and forget. Provides concrete examples like user's target ticker, address, research notes.

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

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

Beyond annotations (readOnly, idempotent), description discloses that mark_read:true modifies read state to affect future calls. This adds crucial behavioral context for a tool that is primarily read-only but has an optional side-effect.

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?

Every sentence adds essential information without redundancy. Core action front-loaded, then specific fields, filtering options, side effect, and alternative access method provided concisely.

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

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

Despite no output schema, description covers return fields, filtering, side effects, and alternative access. Sufficient for agent to understand tool behavior and integrate correctly.

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

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

Schema covers all parameters with descriptions (100% coverage). Description adds practical context like 'set mark_read:true to flag returned events read so the next call only shows newer ones', which is more helpful than the schema alone.

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

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

Description clearly states 'Pull fired events from your subscription feed' providing a specific verb+resource. It distinguishes from siblings like list_subscriptions or recent_changes by focusing on alerts/events from the subscription feed.

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?

Clear when-to-use for retrieving recent alerts, mentions polling suitability and alternative REST endpoint. Lacks explicit when-not or comparison to sibling tools, but provides practical guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it fans out to multiple external sources, has fallback logic (GDELT→GNews), soft-fails for USPTO, and returns structured changes with URIs. No contradictions with annotations.

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

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

The description is a single dense paragraph containing many details. While every sentence adds value, it could be more structured (e.g., bullet points for parameters or sources) to improve scannability. It is not overly long but moderately dense.

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 explicitly states the return format: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers purpose, parameters, behavior, sources, and alternatives, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds valuable meaning beyond the schema. It explains the 'since' parameter format (ISO date or relative shorthand like '7d', '30d', '3m', '1y') and provides usage guidance (e.g., 'Use \"30d\" or \"1m\" for typical monitoring'). It also clarifies that 'type' is limited to 'company' and 'value' can be a ticker or CIK.

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

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

The description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific examples like 'What's new with X'. It lists the data sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes from the sibling tool 'entity_profile', which covers static profiles.

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

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

The description provides clear use-case examples ('What's new with X', 'latest on Y') and explicitly advises when to use the alternative 'entity_profile' instead. It also explains fallback behavior between GDELT and GNews, giving context on when each is used.

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 context beyond annotations: it explains the storage mechanism (key-value pair scoped by identifier), retention details (24 hours for anonymous, persistent for authenticated), and that it is non-destructive. Annotations indicate idempotentHint=true and destructiveHint=false, which the description aligns with without contradiction.

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

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

The description is a single well-structured paragraph that covers all necessary aspects without redundancy. Every sentence contributes essential information: purpose, usage, storage behavior, persistence, and relationships to other tools.

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 (2 parameters, no output schema), the description is thorough. It explains scope, persistence, and how to use with siblings (recall, forget). No gaps in context for an agent to understand when and how to invoke.

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 both parameters are documented. The description adds value by explaining the overall purpose and giving example values (e.g., 'subject_property', 'target_ticker'), enhancing understanding beyond the raw schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' with a specific verb (save) and resource (key-value memory store). It distinguishes from sibling tools recall and forget, making the purpose unambiguous.

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

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

The description explicitly tells when to use ('when you discover something worth carrying forward') and notes alternatives: 'Pair with recall to retrieve later, forget to delete.' It also explains persistence differences for authenticated vs anonymous sessions.

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 safety hints (readOnly, idempotent, non-destructive). The description adds valuable behavioral details: it cascades through multiple lookup endpoints, replaces 2-3 manual lookups, and specifies exact outputs per type (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). 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 well-structured with leading examples and clear sections. It is somewhat lengthy but every sentence adds value; 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?

Given the complexity of two entity types with different return data and multiple internal lookups, the description is thorough. It explains what is returned for each type (identifiers, names, citation URIs) and mentions how it replaces multiple manual steps, all 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?

Schema coverage is 100%, but the description adds significant meaning: for 'type' it lists supported types and their outputs; for 'value' it provides concrete examples and accepted formats (ticker, CIK, name for company; brand or generic for drug), plus mentions auto-disambiguation for company.

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

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

The description clearly states it resolves a user-spoken name to a canonical identifier, with specific examples like 'ticker for...' and 'CIK for...'. It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID', positioning it as the primary tool for ID resolution.

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

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

The description explicitly advises 'Use FIRST whenever you have a name but need an ID', providing clear context for when to use. It does not explicitly mention when not to use or name alternatives, but the purpose is well-defined.

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

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

The description elaborates on the internal behavior (probing each entity with ai_visibility_check, ranking by score) beyond the annotations. All annotations (readOnly, openWorld, idempotent, non-destructive) are consistent and the description adds useful behavioral context.

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

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

The description is two concise sentences plus a parenthetical example. It front-loads the main action and includes a relatable use-case question. No wasted words.

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

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

Given the tool has 4 parameters (all documented in schema) and no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It covers the essential behavioral aspects for a read-only comparison tool.

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

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

The schema covers all parameters with descriptions (100% coverage). The description adds semantic value by noting that the first entity is treated as the 'subject' for narrative purposes, which is not in the schema. This justifies above the baseline of 3.

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

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

The description uses a specific verb ('Compare AI visibility across multiple entities') and resource, clearly distinguishing it from the sibling 'ai_visibility_check' which checks a single entity. It also explains the internal mechanics (probes each entity with ai_visibility_check).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and implies that for a single entity check, one should use 'ai_visibility_check'. However, it doesn't explicitly state when not to use this tool or list alternative tools.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds critical behavioral details: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This transparently handles timeout behavior without contradiction.

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

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

The description is relatively long but densely packed with valuable information. It is well-structured: purpose first, then what's checked, usage guidelines, ecosystem limitation, and finally partial failure behavior. Every sentence adds value, though it could be slightly more concise.

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

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

Without an output schema, the description thoroughly explains the return value: 'summary block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and a list of recent alternative versions.' It also covers partial failure scenarios, making it contextually complete for a complex tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaning by noting that scoped packages (e.g., '@types/node') are accepted and that version defaults to latest when omitted, which is useful 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 is a composite check for npm packages covering license, advisories, version history, and bundle size. It explicitly says 'Composite "should I add this npm package to my project" check in ONE call', and differentiates from siblings by focusing on npm dependency analysis, which no other tool does.

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

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

The description provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also specifies the ecosystem limitation ('NPM ecosystem only in v1') and directs to deps.dev for other ecosystems, giving clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description does not need to repeat these. The description adds the source name and example but no additional behavioral traits (e.g., rate limits, response size). No contradiction detected.

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 two sentences plus a concise example, with no redundant information. It front-loads the core function and filters, and the example demonstrates typical usage efficiently.

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 8 parameters fully described in the schema and comprehensive annotations, the description covers the main functionality and source. However, it lacks details on return format or pagination behavior, which would be helpful given the absence of an output schema. Still, it is sufficient for most agents.

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

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

Schema description coverage is 100%, with each parameter having a clear description in the schema. The description reinforces filters and provides an example usage, which adds some value but does not significantly exceed the schema's information. Baseline score of 3 is appropriate.

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

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

Description clearly states verb 'Search', resource 'global news', and specifies the source 'Currents (70k+ sources)'. It distinguishes from sibling 'latest_news' which likely returns news without keyword search.

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

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

Description provides clear context for when to use this tool (keyword-based news search) and lists available filters (language, category, country, date range). It includes an example and indirectly references sibling 'list_categories' for the category parameter. However, it does not explicitly state when not to use or compare with siblings like 'latest_news' or 'list_categories'.

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 embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping windows), and character cap (200K with truncation flag). Adds significant context beyond annotations (readOnlyHint, etc.) without contradiction.

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

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

Front-loaded with core purpose; all sentences earn their place. Slightly dense single paragraph could benefit from structuring, but remains efficient.

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

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

Thorough for a complex tool: covers truncation, embedding details, pairing advice, and return format despite no output schema. No gaps for intended 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. Description adds value by giving query examples and mentioning return characteristics (passages with offsets and scores), exceeding schema info.

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

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

States specific verb+resource: 'Semantic search INSIDE a fetched record.' Clearly differentiates from siblings (e.g., search_news, ask_pipeworx_grounded) by describing its unique value of returning passages with offsets.

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

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

Explicit usage guidance: 'Use when the record is too big to cram into the prompt.' Describes pairing with ask_pipeworx_grounded, providing clear context for when to use.

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

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

Adds significant context beyond annotations: account requirement, return of subscription id, delivery channel behaviors (always-on feed, optional email/sms/webhook), SMS cap, webhook auto-disable after 10 failures, and signing secret. 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?

Somewhat lengthy but well-structured with front-loaded purpose and bullet-like details. Every sentence adds value; minor redundancy could be trimmed.

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

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

Covers account requirements, type examples, delivery options, and limitations. No output schema, but response (subscription id) is mentioned. Lacks explicit error cases and idempotency details, but overall sufficient.

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

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

Schema coverage is 100%, and description enriches with concrete examples (e.g., sec_8k with items codes, delivery details like verification and webhook signing). 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?

Clearly states it creates a proactive monitoring subscription to a live-data event stream. Distinguishes from siblings like list_subscriptions (lists existing) and unsubscribe (removes).

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?

Specifies when to use (creating a subscription) and prerequisites (Pipeworx OAuth account). Lists supported types and delivery channels with limitations. Lacks explicit alternatives but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that the results are 'drawn from the live catalog of thousands of tools' and that calling with no arguments gives the full spread. This provides useful context about the dynamic nature and scope of the results.

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 concise given the amount of information. It front-loads common queries, then describes the output and usage. Every sentence adds value, though it could be slightly tightened without loss.

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

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

Despite no output schema, the description thoroughly explains the return format: category-bucketed example questions with exact tool+argument shape. It covers use with/without topic, making it complete for an onboarding tool.

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

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

Schema coverage is 100% with one optional parameter 'topic' having a description. The description adds examples of topic values (finance, pharma, etc.) and explains the effect: focus the results. It also clarifies behavior when omitted, adding value beyond the schema.

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

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

The description clearly states it is the onboarding entry point, returns category-bucketed example questions, and describes the categories (company financials, drugs, etc.). It uses specific verbs like 'returns' and 'focus' and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by specifying its role as a first-step tool.

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

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

The description explicitly instructs to use this tool FIRST when the agent does not know what Pipeworx can do. It explains the optional topic parameter to focus on a category. While it does not explicitly exclude other tools, the context implies it is the starting point. It could mention alternatives for specific queries but is sufficient.

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 explaining ownership enforcement, deactivation (not deletion), and that historical events remain accessible via recent_alerts. Annotations already indicate non-destructive, idempotent, and read-write nature, but the description enriches this with practical behavior.

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

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

The description is concise with two sentences, front-loading the action and then providing essential behavioral details. No unnecessary words or redundancies.

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

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

Given the simple tool (1 param, no output schema), the description is complete: it explains the effect on the subscription, ownership, and impact on historical data, leaving no obvious gaps for an agent to misuse.

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

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

Schema coverage is 100% for the single parameter 'id', and its description is adequate. The description adds no further parameter-level details beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'), distinguishing it from sibling tools like subscribe or list_subscriptions. It also specifies ownership enforcement, which further clarifies its scope.

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

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

The description implies when to use (when you want to cancel your own subscription) but does not explicitly state when not to use or compare to alternatives like unsubscribe vs. deactivate. However, the context from sibling tools and the clear action make usage clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds detailed return values (verdict, structured form, actual value with citation, percent delta), explains the data sources (SEC EDGAR + XBRL), and mentions it replaces multiple sequential calls. No contradiction with annotations.

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

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

The description is two paragraphs, front-loaded with common query patterns and purpose. Every sentence adds value, but it could be slightly more concise without losing information. The structure is logical and easy to scan.

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

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

Despite having no output schema, the description fully explains the domain, sources, return format, and limitations. It provides sufficient context for an agent to understand when and how to use the tool effectively, including replacing multiple sequential calls.

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 includes a description for the claim parameter. The tool description adds context with examples and clarifies the natural-language nature, which enhances the schema's meaning. The added value justifies a score above baseline 3.

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

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

The description clearly states the tool validates natural-language claims against authoritative sources, with specific examples ('fact check', 'verify'), and distinguishes its scope (company-financial claims). The verb 'validate' and resource 'claim' are precise, and the inclusion of query patterns helps the agent understand exactly what the tool does.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes current limitations (v1 supports company-financial claims) and contrasts with sequential alternatives. However, it does not explicitly exclude use cases or compare with sibling tools, leaving some ambiguity.

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