Rss2json

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds output format details (per-model {score, confidence, signals, raw_response} + combined view) and the fact that Anthropic calls require a BYO key with direct payment. It does not mention rate limits, failure modes, or data retention.

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence provides necessary information: what the tool does, default model, optional BYO key, return format, and use cases. No redundant or verbose language.

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?

Description covers the return structure and model selection, but lacks details on how 'confidence' and 'signals' are derived, potential failure scenarios (e.g., unknown entity), and pricing implications beyond the Anthropic key note. Without an output schema, more detail on the return format would improve completeness.

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

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

Schema description coverage is 100%, so baseline 3. The description adds little beyond the schema: it reiterates that 'models' supports 'workers-ai' and 'anthropic', and that '_apiKey' is needed for Anthropic. No additional semantic guidance or examples are provided.

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

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

The description clearly states the verb 'probe', resource 'LLMs for business/brand/topic', and outcome 'score visibility (0-100)'. It distinguishes from siblings by specifying use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. However, it does not explicitly contrast with sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence'.

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

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

The description provides usage contexts ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and notes default model vs. option requiring _apiKey. However, it does not explicitly state when not to use or suggest alternative tools for different scenarios, such as direct Q&A via 'ask_pipeworx'.

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, openWorld, and non-destructive. The description adds that it routes to internal tools, fills arguments, and returns structured answers with stable citation URIs, which provides behavioral insight beyond the annotations.

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

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

The description is front-loaded with the key guidance ('PREFER OVER WEB SEARCH') and efficiently lists domains and examples. 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?

Given the tool's complexity (routing to 3,745 tools) and simple input (just a question), the description adequately explains purpose and usage. It could mention output format more explicitly, but the examples and citation URI mention suffice.

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 (100% coverage) with aliases. The description adds value by explaining that the question is in natural language and providing examples, but the schema already defines the parameter clearly.

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 routes questions to a large set of verified sources (3,745 tools across 884 sources) and returns structured answers with citations. It provides specific domains (SEC filings, FDA data, etc.) and example questions, making its purpose distinct from web 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?

Explicitly advises 'PREFER OVER WEB SEARCH' for factual questions and lists many use cases (e.g., 'current US unemployment rate', 'Apple's latest 10-K'). Provides concrete examples of when to use, helping the agent select this tool over alternatives.

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

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

Discloses behavioral traits beyond annotations: costs one extra LLM call, returns explicit refusal reasons (not_in_source, no_tool_match, etc.), and details output structure. Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint; description adds context 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?

Four dense sentences, each earning its place: purpose, behavior, usage guidance, and cost tradeoff. Front-loaded with key value proposition. 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's complexity (6 aliased parameters), annotations covering behavior, and absence of output schema, the description provides complete guidance: output shape, refusal reasons, cost tradeoff, and when to use. Agent can correctly select and invoke the tool based on this alone.

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 as aliases for question. Description adds meaning by stating 'Your question in natural language' and listing accepted aliases, providing practical guidance beyond the schema's repetitive alias descriptions.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling 'ask_pipeworx' by specifying it extracts answers only from tool results and returns refusal reasons.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when to prefer sibling: 'prefer ask_pipeworx for casual lookups.' Also notes cost tradeoff: 'Costs one extra LLM call vs ask_pipeworx.'

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds extensive behavioral details: resolver contract with market_match_confidence, parent_event extractor, news fallback mechanisms, safety checks (low-confidence short-circuits, closed market skip), wide-spread illiquidity note, and resolution-rule risk parsing. No contradictions with annotations, and these details significantly aid agent decision-making.

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 verbose, spanning multiple paragraphs with extensive examples, resolver details, and return shape descriptions. While the information is valuable, it could be significantly condensed or structured for faster agent parsing. Front-loading is present but lost in the length.

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

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

For a complex tool with no output schema, the description provides comprehensive context: return fields (market, analysis, evidence), resolver contract, parent_event extractor, news fallback, safety paths, and resolution-rule risk. It covers all scenarios an agent might encounter, making it complete despite the lack of 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 description coverage is 100%, with all three parameters described in the input schema. The description reiterates the market parameter's flexibility (slug, URL, question) and provides examples, but adds little new semantics beyond the schema. Baseline 3 is appropriate as the schema already does heavy lifting.

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 input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The list of classifiers and fan-out examples further clarifies scope. While it doesn't explicitly differentiate from sibling tools like polymarket_edges, the use cases presented ('should I bet on X') are distinct enough.

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

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

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also includes important usage considerations like low-confidence resolution, closed market handling, and wide-spread warnings. It does not explicitly state alternatives, but the 'use for' provides clear 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?

Goes beyond annotations by detailing data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinical trials for drugs), specific metrics (revenue, net income, cash, debt), handling of off-calendar fiscal years, result sorting by primary metric, and output format including citation URIs. No contradictions with annotations.

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

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

Despite length, every sentence adds new information. Front-loaded with natural language triggers, logically organized by purpose, data sources, sorting, and output. 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 only 2 parameters and no output schema, the description is remarkably complete. Explains both entity types, specific data fields, handling of fiscal year anomalies, result sorting, and citation URIs. Complements annotations well.

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

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

Schema coverage is 100% but description adds practical value with examples of tickers/CIKs for companies and drug names, and clarifies the type parameter. This enriches understanding beyond schema, warranting a 4.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call, listing example queries. It distinguishes itself from siblings by explicitly replacing 8-15 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?

Provides explicit when-to-use guidance with example natural language triggers like 'X vs Y' and 'rank these companies'. Directly says 'ALWAYS PREFER over sequential single-pack lookups', giving clear preference and implicit exclusion of single entity queries.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context: decomposition into sub-questions, parallel routing across 3,751 tools and 886 sources, expected latency (15-60s), and account/payment requirements. 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?

At ~120 words, the description is dense but well-structured. It front-loads the core benefit and follows a logical flow: what it does, how it works, when to use, prerequisites, timing. Every sentence adds value; no filler.

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

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

Despite missing output schema, the description thoroughly describes the return type: 'structured findings packet with verbatim evidence, confidence, source, fetched_at, and a stable pipeworx:// citation... with explicit gaps[].' It also covers prerequisites, timing, and use cases – fully sufficient for a research tool of this complexity.

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

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

Input schema covers both parameters with full descriptions. The description adds value by explaining depth values: 'quick=3, standard=5 (default), thorough=8 (paid plans)' – converting enums to concrete numbers and linking to pricing. Schema coverage is 100%, so baseline is 3, but the extra context earns a 4.

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

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

The description opens with 'Grounded multi-source research in ONE call,' specifying the action (research), the resource (multi-source, grounded), and the uniqueness (one call). It clearly distinguishes from sibling tool ask_pipeworx by stating 'use ask_pipeworx for single lookups — it's one LLM call instead of many.'

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

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

Explicitly states when to use: 'Use for broad or multi-part questions' and when not to: 'use ask_pipeworx for single lookups.' Also provides context on prerequisites ('Requires a Pipeworx account') and tier limits ('depth:'thorough' requires a paid plan').

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that results are ready to call directly with curated examples, though it doesn't mention rate limits or query limits beyond the parameter.

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

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

Front-loaded with key info: 'Find tools by describing the data or task.' followed by usage, examples, and return description. Efficient but slightly long.

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 6 parameters (1 required) and many siblings, the description is complete: covers usage, return value (top-N tools with schemas), and examples. No output schema, but description explains what is returned.

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%. The description adds value by listing example queries and explaining that the query parameter accepts natural language, including all aliases (task, q, search, 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 discovers tools by describing data or task, lists specific domains (SEC filings, financials, etc.), and specifies it returns top-N relevant tools with full schemas. This distinguishes it from siblings like search_within or entity_profile.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance and implying 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?

Discloses operational details beyond annotations: fans across multiple sources, returns specific fields, mentions patent API sunset and soft-fail behavior, and uses a fallback chain (GDELT→GNews). Annotations already indicate safety, but description adds rich behavioral context.

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

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

The description is information-dense but lengthy, with multiple example queries and detailed output enumeration. Could be more concise by trimming examples or moving some detail to a 'returns' section. Still clear but not maximally efficient.

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

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

Given no output schema, the description fully enumerates return fields (CIK, filings, fundamentals, patents, news, LEI) with formatting notes. Covers parameter requirements, limitations, and fallbacks. Complete for this 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 covers both parameters with descriptions. Description adds nuance: 'value' can be ticker or zero-padded CIK, names not supported, and clarifies the 'type' enum is limited to 'company'. Adds value beyond schema.

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

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

The description clearly states it produces a full cross-source profile of a US public company, with example queries like 'Tell me about X' and output details. It distinguishes itself from sibling tools like resolve_entity and compare_entities by advocating direct use over chaining single-pack lookups.

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

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

Explicitly advises using this tool for holistic views over chaining separate lookups, specifies acceptable inputs (ticker or zero-padded CIK), and directs name queries to resolve_entity. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, indicating a safe read operation. The description adds the output format (JSON) but does not disclose rate limits, API key implications, or other behaviors 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 very concise (6 words), which saves space but sacrifices necessary detail. It is front-loaded but under-specified.

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 good annotations and an output schema, the description lacks information about parameter semantics, third-party API usage (rss2json), error behavior, and limitations. It is too brief for a tool with 3 parameters.

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

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

Schema coverage is low (33%), with only 'api_key' having a description. The description itself does not mention any parameters or their meanings, failing to compensate for the schema gaps.

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

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

The description clearly states the verb 'Fetch' and the resource 'RSS/Atom feed' with format 'as JSON'. It is specific and distinguishes the tool from sibling tools like 'validate_claim' or 'search_within'.

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 no guidance on when to use this tool versus alternatives. It does not mention contexts, exclusions, or sibling tool comparisons.

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

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

Description matches annotations (destructiveHint=true) and adds context about clearing sensitive data. No contradictions. Could mention irreversibility, but annotations already indicate destructive.

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: first states action, second gives usage context. 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 1-param delete tool with annotations, description is fully adequate – covers purpose, when to use, and pairing suggestions.

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 no extra meaning beyond schema. Baseline 3 per calibration.

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 'Delete a previously stored memory by key' – specific verb (delete) and resource (memory by key). Distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'context is stale, the task is done, or you want to clear sensitive data...'. Also suggests pairing with siblings, though no explicit when-not-to-use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by explaining the extraction process (fetches page, extracts title/description/key links) and output format, which is valuable beyond the annotations.

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

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

The description is concise with three sentences. It front-loads the core purpose, then explains the process and use cases. Every sentence contributes 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 low complexity (2 params, no output schema) and rich annotations, the description is complete. It explains what the tool does, how it works, and the output format, making it fully contextual for an AI agent.

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

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

Schema coverage is 100% with both parameters well-described. The description does not add significant meaning beyond the schema, mentioning 'full URL' and 'max links' but not adding new syntactic or semantic details, so 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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource. It is specific to this tool and distinct from sibling tools like 'scan_competitor_ai_presence' or '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 lists explicit use cases (getting a client's site indexed, drafting for own project, auditing competitors) and implies when to use it, but does not explicitly state when not to use it or provide direct 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 specific fields but doesn't disclose further behavioral traits 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?

Two sentences, front-loaded with purpose and return fields, 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 list tool with one optional parameter and good annotations, the description is sufficient. It lists return fields even without an output schema.

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

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

Schema coverage is 100% and the description does not add extra meaning 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 lists the caller's active subscriptions, specifies the returned fields, and distinguishes it from sibling tools like subscribe and unsubscribe by being the list action.

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

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

Explicitly says to use this tool to review subscriptions before adding more or to find an id to cancel, providing clear context for when it's appropriate.

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

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

Annotations are minimal (readOnlyHint false, etc.), but the description adds substantial behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that the team reads digests daily and signal affects roadmap. This goes well beyond what annotations provide, with no contradictions.

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

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

The description is concise and front-loaded: it starts with purpose, then usage guidance, then do's/don'ts, then behavioral constraints. Every sentence adds value; there is no redundancy or filler.

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

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

Despite having no output schema, the description fully covers the tool's purpose, parameters, usage conditions, and behavioral traits. It explains what the team does with feedback and addresses the nested context object. The tool is simple and the description is complete for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. However, the description significantly adds meaning: explains each enum value in detail ('bug = something broke or returned wrong data...'), gives specific guidance for message ('Be specific... 1-2 sentences typical, 2000 chars max'), and clarifies the context object. This exceeds the baseline.

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

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

The description opens with a clear purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs and resource (feedback to Pipeworx team) and distinguishes itself from sibling tools by clearly stating it's for bugs, features, data gaps, or praise, which none of the siblings cover.

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

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

The description explicitly says when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides 'don't' guidance: 'don't paste the end-user's prompt.' Additionally, it mentions rate limits and that it's free, setting clear expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (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?

The description is concise (three sentences) and front-loaded with the core purpose. Every sentence adds value with no redundancy or 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 simplicity (1 optional param, no output schema), the description fully covers what the tool returns (top tools, top packs, call volume) and caching behavior. No gaps remain for an agent to use it correctly.

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

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

Schema coverage is 100% with a well-described enum parameter. The description adds meaning by explaining window trade-offs (shorter vs longer windows surface different trends), going 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 it returns 'top tools, top packs, and total call volume' over a window, using specific verbs and resource. It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on trending data from other agents.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. It implies usage context but does not explicitly contrast with sibling tools or state when not to use.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive. The description adds extensive behavioral details: the types of checks (monotonicity, partition sum), response structure, fill-check logic, and limitations (e.g., realizable_edge_pp ≤ 0 means do not trade). No contradictions with annotations. The description significantly enriches the agent's understanding of tool 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 detailed and front-loaded with the requirement. It covers many aspects but is somewhat dense and could benefit from more structured formatting (e.g., bullet points). However, every sentence adds value, and the length is justified by the tool's complexity. It is not wasteful, just slightly 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 absence of an output schema, the description fully explains the return values (opportunities[] with fields, partition_check object) and even covers edge cases (no args fail, placeholder slugs, low similarity, fill check). It also points to the related tool `polymarket_fill_risk` for custom sizing. The description is remarkably complete for a complex analysis tool.

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

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

Schema descriptions for `event` and `topic` are already informative, but the tool description adds substantial extra meaning: explains modes in detail, provides example values, mentions that full Polymarket URLs are accepted for event, and describes the internal processing. This goes well beyond the schema, fully compensating for any need.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, making it easy to understand the resource and verb. Sibling tools like polymarket_edges or polymarket_fill_risk serve different purposes, so this tool's unique role is well-defined.

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 'REQUIRES one of `event` OR `topic`' and recommends event for specific markets and topic for cross-event scanning. It mentions cross-event mode catches patterns single-event misses. However, it does not explicitly state when not to use this tool or list alternatives among siblings, which would have earned a 5.

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

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

Beyond the annotations (readOnlyHint, etc.), the description provides extensive behavioral details: caching behavior ('Cached 1h at the KV level keyed on all knobs'), model explanations, response structure (including diagnostics for empty segments), and warnings about edge already being in price. This adds significant value beyond what annotations convey.

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

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

The description is excessively long and dense with technical details, such as exact model formulas and fudge factors. While thorough, it could be significantly condensed and restructured for better readability. The length reduces its effectiveness for an AI agent.

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

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

Given the parameter count (9), absence of output schema, and complexity, the description is exceptionally complete. It covers all necessary aspects: purpose, model families, response structure (including diagnostics), caching, filter knobs, edge cases (e.g., Fed bets, partition filtering criteria), and a warning about recent price moves.

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 individual parameter descriptions. The tool-level description adds context by grouping parameters into 'TRADEABLE-EDGE KNOBS' and explaining how they interact (e.g., min_liquidity and max_spread_pp drop unrealizable opportunities). This provides additional semantic 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and the detailed breakdown of model families and segments implicitly distinguishes it from sibling tools like polymarket_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 states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides context for when to use the tradeable-edge knobs and notes that Fed bets are excluded from ranking, offering some guidance on alternatives. However, it does not explicitly contrast with sibling tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds details on returned data (tracked, expired, snapshot_dates), decay computation, and limitations. No contradiction.

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

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

Description is detailed and well-structured (purpose, args, response, limits) but somewhat verbose. Could be slightly more concise without losing meaning.

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

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

Given there is no output schema, the description provides a thorough breakdown of the response structure (tracked, expired, snapshot_dates) and edge attributes, making it self-contained.

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 default values (14 days, '1wk') and clarifies the meaning of window, adding value beyond schema.

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

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

The description clearly states it answers 'how long has this edge existed and is it shrinking?' and provides telemetry on edge persistence and decay. It distinguishes itself from sibling tools like polymarket_edges (which likely provides current edges) and polymarket_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?

Explicitly explains the use case: comparing fresh vs. old edges. Mentions limits (60-day TTL, not intraday) but does not provide explicit when-not or alternatives.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral details: walks the order book ladder, returns slippage, fill details, and warns about partial basket fills converting arb into unhedged directional positions. No contradiction.

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

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

The description is dense but well-structured with bold headings for modes. It is longer than necessary but every sentence adds information. Front-loads the core purpose. Minor redundancy in return field listing could be tighter, but overall efficient.

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

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

Given no output schema, the description thoroughly explains all return fields for both modes, including edge cases like thin legs, forced directional risk, and maximum clean notional. It covers critical behavioral details for safe usage.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds additional meaning: default values (size_usd=1000, side auto-detect for basket), interpretation of size_usd in basket mode as settlement notional, and mode-specific semantics. This provides 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 as a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate usage.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (thin books, partial fills causing directional risk) and notes required parameters (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?

Beyond annotations (readOnly, openWorld, idempotent), description details response fields (leg prices, spreads), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains conditions where spreads are meaningless, providing complete behavioral transparency.

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

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

Description is lengthy but well-structured with clear sections for purpose, modes, response, and safety fields. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the complexity of cross-venue spreads and no output schema, the description adequately explains response structure, edge cases, and warnings, making it complete for effective tool invocation.

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

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

Schema coverage is 100%, and the description adds meaning by listing the 10 pre-mapped topic values, explaining how explicit parameters override topic mapping, and providing example usage, all of which enriches the parameter understanding.

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

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

Description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools like polymarket_arbitrage or bet_research by focusing on cross-venue comparison.

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

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

Provides two usage modes (topic shortcuts and explicit tickers) and warns that most pre-mapped topics currently return compatibility_warning, guiding appropriate use. However, it doesn't explicitly compare with sibling tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping ('Scoped to your identifier') and pairing with 'remember' and 'forget', which is valuable beyond the annotations. No contradiction.

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

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

Three sentences: first states core function, second gives usage examples, third adds scoping and pairing. No wasted words, front-loaded with the main action.

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

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

Given the tool has one optional parameter and read-only semantics, the description covers purpose, usage, scoping, and pairing. No output schema is provided, but the description implicitly indicates return types (value or list of keys), which is 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% with one optional parameter. The description adds meaning by explaining the effect of omitting the key (list all keys) versus providing it (retrieve value), which is not evident from the schema alone.

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

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

The description explicitly states the verb 'retrieve' and the resource 'value previously saved via remember' or 'list all saved keys'. It clearly distinguishes from siblings like 'remember' and 'forget' by naming them and explaining the relationship.

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

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

The description provides explicit context for when to use ('look up context the agent stored earlier') with concrete examples. It implies when not to use (if saving, use 'remember') but does not explicitly state alternatives or 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?

The description fully discloses the behavior: it returns alerts with specific fields, allows filtering by type and timestamp, and explains the mark_read side effect (flagging events as read). It also notes that polling is appropriate. This adds significant context beyond the annotations, even though the mark_read feature contradicts the readOnlyHint annotation.

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

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

The description is four sentences, front-loaded with the main purpose, then details return payload, parameter usage, and a note on polling. Every sentence adds value with no redundancy or 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 5 optional parameters and no output schema, the description covers the core behavior: return fields, filter options, mark_read effect, polling suitability, and an alternative endpoint. It lacks details on error conditions or authentication but is fairly complete for a list retrieval tool.

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

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

All parameters are described in the schema (100% coverage). The description adds meaningful examples for 'type' and 'since' (e.g., 'sec_8k') and explains the effect of 'mark_read'. However, 'unread_only' is not elaborated beyond the schema. The added value is modest, keeping the score at 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 pulls fired events from the subscription feed, returns most recent alerts with specific payload fields (source, citation_uri, raw event), and lists filtering options. It is specific and actionable, distinguishing itself from generic feed retrieval by focusing on alerts from the evaluator.

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 mentions that polling works fine and provides an alternative REST endpoint, offering some usage guidance. However, it does not explicitly compare this tool to siblings like 'feed' or 'recent_changes', nor does it state when to prefer this tool over others.

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 show readOnlyHint=true, idempotentHint=true, etc. The description adds valuable behavioral context: fallback logic, soft-fail for USPTO PatentsView sunset, and result structure (grouped changes, total_changes, 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 informative but slightly verbose with parenthetical asides. It is front-loaded with example queries and efficiently conveys the tool's core purpose and behavior in a structured manner.

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

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

Despite no output schema, the description fully explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It also covers multiple fallback mechanisms and edge cases (soft-fail), making it 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% and description significantly enriches parameter meaning: 'since' gets examples of both ISO and relative shorthand ('7d', '3m', '1y'), 'value' explains ticker or CIK, 'type' noted as only 'company'. No extra parameters needed.

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

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

The description uses specific verbs like 'fan out', 'returns structured changes', and explicitly contrasts with sibling tool 'entity_profile'. It clearly states the tool provides a change feed for a company over a time window, aggregating multiple sources.

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 concrete example queries ('latest on Y', 'updates on Acme') and explicitly states when to use the alternative 'entity_profile' instead. It also explains fallback behavior (GDELT→GNews) and soft-fail for USPTO.

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 give idempotentHint=true, readOnlyHint=false, destructiveHint=false. Description adds context on scoping by identifier, persistence for authenticated vs anonymous, and 24-hour expiration for anonymous sessions. No contradiction with annotations. Could mention auth failure handling but overall strong.

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 clear sentences, front-loaded with the purpose, then usage guidance, then behavioral details. 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?

With 2 parameters, good annotations, and clear sibling context, the description fully informs an agent about when and how to use the tool. No output schema is fine since the tool only stores data.

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

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

Schema coverage is 100% with descriptions for key and value. Description adds context: 'key-value pair scoped by your identifier' and provides examples of keys (subject_property, target_ticker, user_preference) and values (findings, addresses, preferences). This adds meaning beyond schema.

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

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

The description starts with a specific verb+resource: 'Save data the agent will need to reuse later'. It clearly distinguishes the tool from its siblings 'recall' and 'forget' by stating the 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?

Explicitly states when to use: 'when you discover something worth carrying forward' and provides alternative tools: 'Pair with recall to retrieve later, forget to delete.' Also clarifies scope and persistence differences.

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

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

The description adds significant behavioral context beyond the annotations: it explains that each call cascades through several lookup endpoints internally and details the exact return structure for each entity type (company returns ticker, CIK, company_name, citation URI; drug returns RxCUI, ingredient, brand, citation). The annotations already indicate read-only, idempotent, open-world, and non-destructive behavior, and the description does not contradict any of 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 front-loaded with examples and a clear purpose statement. Every sentence provides value, but it is somewhat lengthy. A slight trim could improve conciseness, but it remains well-structured and informative.

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

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

Given the tool has no output schema and only two parameters with full schema coverage, the description compensates well by explicitly describing the return values for each type, including citation URIs. It also explains the internal cascading behavior, making the tool's behavior fully understandable.

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 the schema already documents both parameters thoroughly. The description repeats the parameter details with examples (e.g., 'For company: ticker (AAPL), CIK (0000320193), or name') but does not add new meaning beyond what the schema provides. Therefore, 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 resolves user-spoken names to canonical/official identifiers with specific verb ('resolve') and resource ('entity'). It includes concrete examples like 'What's the ticker for…' and lists supported types (company, drug) with their return values. It also says 'Use FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools like compare_entities or entity_profile.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to use this tool. It also notes that each call replaces 2-3 manual lookups. However, it does not explicitly state when NOT to use it or name specific alternatives, though the sibling tools list provides alternative 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 cover read-only, idempotent, non-destructive. Description adds process details (probes each entity, ranks) and output format (ranked list with score, confidence, signal density), providing useful behavioral context.

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

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

Description is concise, front-loaded with main action, no unnecessary words, effectively communicates purpose and output.

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

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

Despite no output schema, description explains output format adequately. For a tool with 4 parameters and clear annotations, it provides enough context for an agent to use correctly. Could be slightly more explicit about output JSON 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% description coverage for all 4 parameters; description does not add additional meaning beyond what schema provides, thus baseline score 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check probes, and differentiates from sibling ai_visibility_check which does single checks.

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 use-case context ('competitive AI-marketing audits') and example question, but does not explicitly exclude single-entity checks; however, mention of probing multiple entities and ranking implies it's for comparisons.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description adds key behavioral details: partial failure graceful handling, timing of bundlephobia first measurement (5-30s), and what fields are returned if a source fails (sources_failed listed). No contradictions with annotations.

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

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

Description is appropriately sized given complexity. Front-loaded with core purpose, then details on sources, use cases, return values, and limitations. Every sentence adds value; 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?

Completes the picture for a composite tool without output schema. It lists all return fields (summary, advisories, links, alt versions), explains partial failure behavior, and notes ecosystem limits. Sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100% for both parameters with adequate descriptions (npm package name with scoped packages, version defaults to latest). The tool description adds no additional semantic information beyond the schema, meeting baseline but not exceeding.

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

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

The description clearly states the tool's purpose: a composite check for evaluating whether to add an npm package, combining deps.dev and bundlephobia data. It specifies the use case ('is X safe/popular/small') and distinguishes from sibling tools by focusing on npm ecosystem.

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

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

Explicit guidance on when to use: when an agent asks about package safety, popularity, or size. Also clearly states limitations: only npm ecosystem in v1, and directs users to deps.dev:version directly for other ecosystems. Provides no use cases for alternatives.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and offset output. This enriches the agent's understanding of 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 a single paragraph that is well-structured: it starts with purpose, then usage context, then pairing with another tool, then technical specifics. 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 no output schema, the description adequately explains the return type (passages with offsets and scores). All inputs are covered, constraints are stated, and the companion tool relationship is established. No gaps remain for the agent.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds context for the text parameter (truncation and flag) and clarifies query as natural-language, exceeding schema detail. However, limit parameter is only mentioned in 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 'Semantic search INSIDE a fetched record' and explains the inputs (text, query) and outputs (passages with offsets and similarity scores). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and focusing on internal 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?

The description provides explicit guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. It implies when not to use (when prompt can accommodate the full text) but does not explicitly exclude alternatives.

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

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

Annotations indicate mutation, non-destructive, idempotent. Description adds details: returns new subscription ID, always-on feed, optional delivery channels with limitations (SMS cap, webhook auto-disable), and account verification requirement. No contradictions with annotations.

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

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

Description is well-structured with core purpose upfront, then detailed types and delivery options. It is lengthy but each sentence adds value, justifying the length.

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

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

Given the tool's complexity (multiple subscription types, nested params, optional delivery channels, no output schema), the description covers all aspects: required auth, type-specific filters, delivery mechanisms, limitations, and return value (subscription ID). Completely adequate.

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

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

Schema coverage is 100%, but description adds significant value by explaining each subscription type in detail, providing concrete examples, and elaborating on delivery channel behaviors (e.g., webhook HMAC signing, SMS verification). Some redundancy with schema but overall helpful.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 requires a Pipeworx OAuth account, notes that anonymous and BYO users cannot persist subscriptions, and provides type-specific usage examples. However, it doesn't explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds valuable behavioral context: it returns 'category-bucketed example questions… each with the exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools.' This explains the output behavior and dynamic nature beyond the annotations.

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

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

The description is a single dense paragraph that front-loads synonyms and then explains purpose and usage. While it contains all necessary information, it could be more structured (e.g., bullet points for categories) for quicker parsing. It is not excessively long but lacks optimal conciseness.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description covers purpose, usage guidelines, parameter behavior, and contextual role as an onboarding entry point. It fully equips the agent to understand when and how to invoke the tool.

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

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

Schema coverage is 100% with one optional topic parameter described. The description adds meaning by listing example topics ('finance', 'pharma', 'betting') and explaining that omitting topic gives a cross-category spread. This enriches the parameter semantics beyond the schema's enum-like 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 returns category-bucketed example questions for Pipeworx, serving as the onboarding entry point. It explicitly distinguishes from siblings by positioning itself as the first tool to call when the agent doesn't know Pipeworx's capabilities, and it lists the categories and meta-tools to learn.

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 strong usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to use with no arguments or pass a topic. It does not explicitly state when NOT to use, but the context is clear.

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

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

The description adds behavioral details beyond annotations: ownership constraints, deactivation vs deletion, and impact on historical events. It aligns with annotations (readOnlyHint=false, destructiveHint=false) and clarifies idempotentHint=true by noting the row is deactivated.

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 with no superfluous words. It front-loads the action and provides key behavioral context 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?

Given the tool has one parameter, no output schema, and annotations covering safety, the description fully covers purpose, constraints, and post-conditions. There are no gaps.

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

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

Schema coverage is 100% and the parameter 'id' is well-described in the schema. The description adds no further detail about the parameter beyond what is already in the schema, meeting the baseline expectation.

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', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'. It specifies the resource (subscription) and the effect (deactivation rather than deletion).

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

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

It provides guidance on ownership enforcement ('you can only cancel your own subscriptions') and hints at alternatives for historical data ('historical events stay available via recent_alerts'). While it does not explicitly list when not to use it, the context 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by detailing the return format (verdict, structured form, actual value with citation, percent delta) and noting that it consolidates multiple calls. 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 and well-structured. It starts with example trigger phrases, explains when to use, specifies the domain, and lists return values. Every sentence adds useful information 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 simplicity (one parameter, no output schema), the description fully explains the tool's purpose, usage, scope, and what it returns. No gaps remain for an AI agent to understand how and when to invoke it.

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

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

Schema coverage is 100% with a single 'claim' parameter described as 'Natural-language factual claim'. The description reinforces this with multiple examples and clarifies the expected format, adding value beyond the schema definition.

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 is very specific: it identifies the tool as a fact-checker for natural-language claims, with a clear domain (company-financial claims for public US companies). It provides example trigger phrases and distinguishes itself from other tools by noting it replaces multiple sequential calls. No ambiguity.

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

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

The description explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also gives examples of claim formats. However, it does not mention when not to use or suggest alternatives from the sibling list, but the domain restriction is clearly stated.

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