Us News Feeds

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false. The description adds substantial context: it probes multiple models, returns score 0-100 per model, requires API key for Anthropic, and passes it directly. 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 a single focused paragraph that front-loads the action and includes all necessary details: purpose, default model, optional key, return format, and use cases. Every sentence adds value.

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

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

Given 4 parameters (1 required), no output schema, and no nested objects, the description fully explains inputs and outputs (per-model {score, confidence, signals, raw_response} + combined view). Annotations cover safety. It 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%. The description adds meaning beyond schema: explains entity as 'brand/business name, product, etc.', models lists supported values and default, _apiKey notes it's passed straight to Anthropic, and context disambiguates. This fully compensates for lack of enums or nested objects.

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

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

The description uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility'). It clearly states the tool probes LLMs for entity knowledge and outputs a visibility score. This distinguishes it from siblings like 'scan_competitor_ai_presence' which likely has a narrower 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 lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default model vs optional Anthropic key. However, it does not explicitly state when to avoid this tool or mention alternatives, though the sibling list provides some implicit 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 readOnlyHint, openWorldHint, idempotentHint true; description adds that it routes questions to the right tool, fills arguments, and returns structured answers with stable citation URIs. Does not contradict 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 dense but well-structured: starts with key guidance, then examples, then sibling differentiation. Could be slightly trimmed, but every sentence adds value.

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

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

For a tool with 6 parameters (only 1 required) and no output schema, the description is thorough: explains capabilities, sources, use cases, and provides multiple examples. Annotations cover safety aspects.

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 6 parameters with descriptions (100% coverage). Description adds context that the question is routed and arguments are filled, but does not elaborate on parameter semantics beyond the schema.

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

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

Description clearly states it answers factual questions using authoritative structured data across 4,476 tools and 1,127 sources. It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by specifying when to prefer this tool.

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

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

Explicitly instructs to prefer over web search for specific data types. Provides clear when-to-use indicators like 'what is', 'look up', and examples. Also specifies when to step up to alternatives (hallucination-resistant or multi-part questions).

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 discloses extra LLM call cost, structured response with evidence and refusal reasons, and that answer is extracted only from tool result. 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 key concept ('hallucination-resistant'), then efficiently explains routing, extraction, response format, refusal reasons, use cases, and cost tradeoff. 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, description fully documents return format ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and explicit refusal types. Covers behavioral nuances (grounding, cost) that annotations alone miss, 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?

Input schema covers 6 parameters with 100% description coverage, all aliases for 'question'. The description adds no further semantic meaning beyond what the schema already provides (e.g., 'Your question in natural language'). Baseline 3 per rules.

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 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling ask_pipeworx by emphasizing groundedness and explicit refusal reasons. Specific verb 'extracts the answer using ONLY what the tool result contains' clarifies the core function.

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 when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), with cost tradeoff mentioned. Also lists high-stakes domains like financial verdicts, legal claims, medical lookups.

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, read-only behavior. Description adds extensive behavioral details: low-confidence short-circuit, closed market handling, wide spread tradeability, resolution-rule risk, resolver contract, parent event extraction, and news fallback fields.

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?

Very long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). Every sentence adds value, but could be slightly more compact. Front-loaded with main 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 no output schema, the description thoroughly explains the output structure (market, analysis, evidence, resolver contract, parent event, news fields) and covers edge cases (low confidence, closed markets, wide spreads, cancellation rules). Complete for a complex research 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?

Adds significant meaning beyond the input schema: explains categories, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, and safety. Provides context for all three parameters (depth, market, include_raw) with examples.

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 'Research', the resource 'Polymarket bet', and the method 'pulling Pipeworx data'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on research for bet decision support.

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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides context for when to inspect resolver contract (fuzzy matches), and implicitly contrasts 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 declare readOnly and idempotent hints. The description adds significant behavioral details: for companies, it pulls latest 10-K financials from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years; for drugs, FAERS counts. It also mentions sorted results and citation URIs, exceeding annotation coverage.

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 recommendation. It is somewhat verbose but packs necessary details for both entity types. Each sentence serves a purpose, though brevity could be improved.

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 and lack of output schema, the description covers key aspects: source of data, handling of fiscal years, sorting behavior, and return of citation URIs. It is nearly complete, though could include more on pagination or error cases.

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 describes parameters well. The description adds context that for company type, values are tickers/CIKs, and for drug type, names. It also explains what data each type fetches, adding value beyond the schema's enum descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with example queries like 'compare X and Y' and 'rank these companies'. It distinguishes itself from sequential single-pack lookups, which is important given sibling tools like 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 states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use. It also details what data each type pulls, helping the agent choose between company and drug comparison.

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 valuable behavioral context: it's NOT open-web search, expects 15-60s, returns explicit gaps when data unavailable, and decomposes questions into facets. Describes return format (verbatim evidence + confidence + source + fetched_at + citation). 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 long but efficiently packed with essential information. It front-loads the critical account requirement and fallback tool. Every sentence adds value, though some minor repetition exists (mentions '4,476 tools' and '1,127 sources' separately). Could be slightly tighter, but still 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 2 parameters and no output schema, the description provides comprehensive context: account tiers, alternatives, performance expectations, limitations for certain topics, and what the output contains. Given the annotations, the description fills all gaps an agent would need to decide 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 descriptions for both parameters. The description adds meaning by explaining depth values (quick=3, standard=5, thorough=8) and clarifying that the question is natural language. It also provides context about the number of tools (4,476) and sources (1,127), which helps the agent reason about parameter choices.

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

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

The description clearly states it performs 'grounded multi-source research' across structured data sources, decomposes questions into facets, and returns a findings packet. It distinguishes itself from sibling tools like ask_pipeworx by specifying scope and parallel execution. The verb 'research' plus resource 'structured data sources' makes the purpose unambiguous.

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

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

Explicitly tells when to use (broad/multi-part over structured data), when not to (single lookup use ask_pipeworx, breaking news use other tools), and account requirements. Even names alternatives like ask_pipeworx and specifies conditions for paid plans. No ambiguity.

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 crucial behavioral details: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations and clarifies the exact output format.

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 4 sentences long, front-loaded with the core purpose. It includes a helpful list of example domains. While not overly verbose, it could be more concise by trimming the inline examples. Still well-structured 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?

The description explains what the tool returns and that it includes full schemas, compensating for the lack of an output schema. It covers the necessary context for an AI agent to use the tool appropriately. With 6 parameters and 100% schema coverage, the description is complete 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 description coverage is 100% – all 6 parameters have descriptions. The description mentions that 'query' accepts multiple aliases, but this is already present in the schema descriptions. No additional semantic context is provided beyond what the schema already offers. Baseline 3 applies.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes itself from siblings by explicitly saying 'Call this FIRST when you have many tools available' – it serves as a discovery gateway, not a direct query 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 provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies the tool is for exploration, not for direct single-answer queries, but could be more explicit about 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 readOnly, openWorld, idempotent. Description adds details on parallel fan-out across sources, specific return fields, USPTO sunset soft-fail, news fallback, and limitations, enhancing 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?

Description is dense with information and front-loaded with examples, but slightly lengthy; every sentence is valuable, but could be 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?

Given no output schema, description thoroughly explains expected return fields (cik, company_name, filings with URIs, fundamentals, patents with caveat, news, LEI) and fallbacks, fully preparing 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%, but description adds meaning: type is only 'company', value must be ticker or zero-padded CIK, and names unsupported, clarifying format and constraints.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with example queries and explicit mention of preferring it over chaining single-source lookups, distinguishing it from sibling tools like resolve_entity.

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

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

Explicitly says when to use (holistic view) and when not (names not supported, must use resolve_entity first), and prefers over chaining single-source lookups, providing clear direction.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. Description adds value by explaining the CF-robust fallback mechanism and normalization, which is 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?

Three sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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

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

Given the tool's simplicity and the annotations covering safety, the description is complete. It covers purpose, usage, fallback, and sibling advice. No output schema needed.

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

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

Schema coverage is 100%, and the schema itself describes each parameter. The description does not add additional semantic meaning to the parameters beyond what is already in the schema.

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

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

The description clearly states it fetches and normalizes any RSS/Atom/RDF feed by URL. It uses specific verbs and resources, and distinguishes from siblings like 'list_feeds' which is for curated 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?

Explicitly provides guidance: use 'list_feeds' first for curated sources. Also mentions fallback behavior for blocked sources, giving context on 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?

Annotations already indicate destructiveHint: true, and the description confirms deletion behavior. It adds context about clearing sensitive data, which is slightly beyond what annotations provide. No contradictions.

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

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

Three sentences with no wasted words. The first sentence directly states the action, making it efficient and front-loaded.

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

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

For a simple tool with one parameter, destructive nature, and no output schema, the description fully covers purpose, usage context, and pairing hints. It is complete and actionable.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description adds no additional meaning beyond the schema, 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 'Delete a previously stored memory by key', which provides a specific verb and resource. It distinguishes itself 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?

The description explicitly lists scenarios for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with 'remember' and 'recall', providing clear guidance on 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the fetching and extraction process. No contradictions found.

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 efficient, front-loading the main purpose, and consists of four concise sentences without any 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 rich annotations and complete schema, the description adequately covers what the tool does, its output, and relevant use cases. No gaps remain for an agent to understand 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% with clear parameter descriptions. The description adds minimal extra parameter context beyond what the schema provides, meeting the baseline for good coverage.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, explaining the process and output format. It distinguishes itself from sibling tools by specifying a unique, concrete function.

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 (getting client site indexed, drafting for own project, auditing competitor). It lacks explicit when-not-to-use or alternatives, but the context is clear given the sibling list.

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 no destructive action. The description adds context about curated US news but does not further disclose behavior like pagination or rate limits, so it adds minimal value beyond annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and includes essential filtering details and a cross-reference to read_feed. Every sentence contributes value.

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

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

For a simple listing tool with no output schema, the description adequately explains returned fields (id, title, category, source) and filtering. It lacks mention of pagination or default behavior, but the context is sufficient given the tool's simplicity.

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 'query' and 'category' described in the schema. The description restates these parameters with examples ('government, news') but does not add meaning beyond what the schema provides.

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

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

The description clearly states the verb 'List' and the resource 'curated US news, politics & government feeds' with specific fields (id, title, category, source). It distinguishes itself from sibling tools like read_feed by explicitly directing users to pass an id to read_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?

The description provides optional filtering by category or keyword and advises using read_feed for detailed feed content. However, it does not explicitly state when not to use this tool or compare it to siblings like list_subscriptions or fetch_feed.

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, etc. The description adds context about default behavior (active only) and lists returned fields, enhancing transparency beyond annotations.

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

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

Two sentences, efficient and front-loaded: first sentence states purpose and return fields, second provides 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 list tool with one optional parameter and no output schema, the description covers purpose, return fields, parameter effect, and usage context 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 coverage is 100%, so baseline is 3. The description restates the parameter's effect from the schema without adding new meaning, so no extra 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 'List the caller's active subscriptions' with a specific verb and resource, and 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?

Provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Though it lacks negative guidance, it clearly states 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?

Annotations show readOnlyHint=false, destructiveHint=false, but add no specificity. Description adds critical behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota. 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?

Four sentences, each carrying distinct information: purpose, when to use, how to write, and behavioral notes. Front-loaded with the verb phrase. No unnecessary words.

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

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

Despite no output schema, description covers what happens after submission (team digests daily, roadmap impact), rate limits, quota, and content guidelines. For a feedback tool, this is fully 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 description adds value by explaining the 'type' parameter with concrete examples and adds guidance on how to structure the message ('describe in terms of Pipeworx tools/packs'). The 'context' object is well-documented in schema, so description adds minimal extra but sufficient.

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

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

Description clearly states the tool is for sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It specifies the verb 'Tell' and resource 'Pipeworx team', and distinguishes itself from all sibling tools since no other tool provides feedback functionality.

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

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

Provides explicit when-to-use guidance for each feedback type (bug, feature, data_gap, praise, other) and clear instruction on what not to do ('don't paste the end-user's prompt'). It also explains the context of use (when a tool returns wrong data, when a desired tool is missing, etc.), though no direct alternative tool is given as feedback is unique.

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 valuable behavioral traits beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window'. This complements annotations (readOnlyHint, idempotentHint) with concrete source, privacy, and caching details.

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

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

Very concise yet informative. Two sentences cover purpose and returns, followed by three sentences for use cases, source, and caching. No fluff; each sentence adds distinct value. Front-loaded with main purpose.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete. It specifies exact return fields (pack, tool, count), explains aggregation source, guarantees no PII, and notes caching. Use cases and window semantics provide sufficient context 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% with enum values described. Description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This explains the trade-off between windows, going beyond the enum labels.

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 purpose: 'What other AI agents are calling on Pipeworx right now' and specifies 'Returns the top tools, top packs, and total call volume over a recent window'. It distinguishes itself from sibling tools like ask_pipeworx and discover_tools by focusing on trending/popularity rather than direct querying or tool discovery.

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

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

Explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. While it doesn't include explicit 'when not to use' statements, the provided scenarios give clear guidance on appropriate usage contexts.

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 behavior. The description adds significant operational transparency: it explains the computation steps (monotonicity checks, partition check, filler check), failure modes (skipped_low_similarity, placeholder fractions), and when the arb signal is null. It also warns that a positive edge may not be realizable if the book lacks depth. 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 somewhat long but well-structured: it starts with a required condition, then describes each mode, then details response and fill check. Every sentence adds value, though some technical details (e.g., threshold percentages) could be summarized. However, given the tool's complexity, the length is justified and not wasteful.

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

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

With no output schema, the description fully explains the return value: 'opportunities[]' with fields, and 'partition_check' in event mode. It also covers edge cases (null signals, fill check results). The tool has 2 optional parameters but the description tells the agent exactly what to expect, 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?

Input schema coverage is 100% with descriptions, but the description adds substantial meaning: it explains the implications of each parameter, provides example values (slugs, seed questions), describes what happens in each mode (walking child markets vs. searching related events), and details the internal logic (Jaccard similarity, placeholder filter). This goes far beyond the schema's basic 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two distinct modes ('event' for single-event and 'topic' for cross-event), making the purpose specific and unambiguous. Sibling tools like 'polymarket_edges' and 'polymarket_fill_risk' are clearly different, so there is no confusion.

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 that one of 'event' or 'topic' is required, and calling with no args fails. It provides clear guidance on when to use each mode: 'event' recommended for a specific market, 'topic' for cross-event scanning. It also mentions that cross-event mode catches patterns single-event misses and references an alternative tool for custom sizing ('polymarket_fill_risk'), giving complete usage 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 all green (readOnly, openWorld, idempotent). Description adds rich context: caching (1h KV-level), model families, Kelly caps (0.25), tradeable-edge knobs, response structure (by_segment, diagnostics). 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?

Long but well-structured. Front-loaded with purpose, then organized into model families, tradeable-edge knobs, response fields. Every sentence adds value; could trim minor redundancy but clear and efficient for the complexity.

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

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

Given 9 params, no output schema, and complex nested response, the description is highly complete. Explains three segments, diagnostics (why empty), Fed bets, and edge ranking. Leaves minimal ambiguity for an agent to interpret results.

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

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

Schema coverage 100% with detailed descriptions. Description adds contextual value beyond schema: explains min_partition_leg_kelly interaction with min_kelly, slippage_pp market context, and min_liquidity rationale. Baseline 3, incentive for extra context justifies 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?

Description starts with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from sibling tools like polymarket_arbitrage, which likely focuses on cross-market arb, and polymarket_edge_tracker, which may track changes over time.

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 use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' Provides guidance on knobs like slippage_pp ('bump for very thin partitions; drop to 0 if you have a smarter fill model') and explains exclusion of Fed bets ('excluded from ranking…'). Lacks explicit when-not-to-use vs. alternatives.

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

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

The description adds significant context beyond annotations: it details the output structure (tracked, expired, snapshot_dates), data sources (daily snapshots), and limitations (no intraday, TTL). No contradiction with readOnlyHint=true.

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

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

The description is well-structured with a clear opening, detailed response explanation, and limits. While informative, 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?

Given the complexity and lack of output schema, the description thoroughly covers output fields, data freshness, and limitations, making it complete for effective tool selection.

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

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

Schema coverage is 100%, so baseline is 3. The description adds default values and context (e.g., days clamp 2-30, window family) but doesn't provide deeper semantics 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 provides 'edge persistence and decay telemetry' and answers a specific question about edge age and trend. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series 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?

It explains when to use it (comparing fresh vs. aged edges) and includes limits like 60-day TTL. However, it doesn't explicitly state when not to use it or provide alternatives beyond the sibling 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?

Beyond the readOnlyHint and idempotentHint annotations, the description details the tool's behavior: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and for basket mode explains per-leg fill details, thin_legs, forced_directional_risk, and the conversion of partial fills into unhedged directional positions. This fully discloses 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?

The description is well-structured with bold headings (REQUIRES, SINGLE-MARKET, BASKET) and bulleted return fields. Every sentence carries essential information, and length is justified by the tool's complexity. No redundant or filler content.

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 documents all return fields for both modes, including edge cases like thin legs and forced directional risk. It covers all four parameters with their interpretations and constraints, making the tool self-contained 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?

Despite 100% schema description coverage, the description adds significant meaning: explains defaults for 'side' in both modes, interprets 'size_usd' differently for single-market (max spend/target proceeds) vs basket (settlement notional), notes clamp range (10–1,000,000), and distinguishes between market slug/URL and event slug/URL. This goes well beyond the schema.

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

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

Description clearly defines the tool as a realizable-vs-theoretical edge check against live order book depth. It distinguishes two modes (single-market and basket) and explicitly states its role as a prerequisite before acting on arbitrage signals or trades above $500, differentiating it from sibling tools like polymarket_arbitrage and 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?

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'. Also explains the rationale (theoretical overround not capturable, partial fills convert arb to directional position) and states required parameters (one of '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, openWorld, idempotent. The description adds extensive behavioral context: compatibility_warning conditions, temporal alignment, skipped cross types, and counters. No contradiction with annotations.

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

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

The description is long but structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, but could be slightly more concise. However, given the complexity, the length is justified.

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

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

No output schema, so the description fully explains return values: leg-by-leg prices, spread array, safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers all needed context 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%, baseline 3. The description adds meaning: explains the topic enum values, that explicit tickers override, and provides examples. It adds context beyond the schema, justifying 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. Two modes (topic shortcuts and explicit tickers) are explained with examples.

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

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

The description explains when to use each mode: topic shortcuts for 10 pre-mapped macros, explicit tickers for custom pairs. It warns that pre-mapped topics often return compatibility_warning, so they are not always tradeable. However, it does not compare directly to alternatives 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, idempotentHint, and destructiveHint, covering safety. The description adds the normalized items structure but does not discuss errors, auth, or pagination beyond the limit parameter. Acceptable given annotations.

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

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

Two sentences with zero waste, front-loading purpose and result structure. Every sentence is necessary.

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

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

For a simple read tool with rich annotations, the description is mostly complete. It specifies the feed type (US news) and return fields, but lacks detail on default sorting or handling of limit. No output schema increases reliance on description; the return fields help.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema, such as the keyword filter affecting title/summary, but this is already implied.

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 reads a curated US news, politics & government feed by its id, distinguishes from sibling list_feeds by referencing it, and mentions return of normalized items with specific fields. This provides a specific verb+resource+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?

It explicitly advises getting the feed id from list_feeds, and notes optional keyword filtering. However, it does not mention when not to use this tool or compare with sibling fetch_feed, leaving some ambiguity.

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 scoping detail (anonymous IP, BYO key hash, or account ID) beyond annotations. Annotations already indicate safety (readOnly, idempotent, not destructive). 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?

Four sentences, front-loaded with primary purpose, no redundant information. Efficient and clear.

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

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

Fully describes the tool's functionality, scoping, and relationship to siblings. No output schema needed given simplicity.

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 reinforces the optional key behavior with additional explanation of listing all keys when omitted.

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?

Explicitly states the action (retrieve/list), the resource (values saved via remember), and distinguishes from siblings (remember, forget). Examples clarify use cases (ticker, address, notes).

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?

Clearly describes when to use (look up stored context) and pairs with remember/forget. Does not explicitly exclude alternatives, but the context is sufficient for a simple 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. The description adds value by explaining specific response fields (source, citation_uri, raw payload), the effect of mark_read parameter, and that polling is fine. 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 at four sentences, covering purpose, filtering, mark_read behavior, and alternative use. Every sentence adds value with no redundancy. Could be slightly tighter but overall effective.

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

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

With no output schema, the description adequately explains return values (source, citation_uri, payload). It also notes persistence and polling suitability. Parameter details are covered by the schema. Missing explicit pagination or limit explanation, but schema covers defaults (limit default 50).

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 goes beyond schema by providing an example filter value ('sec_8k'), clarifying that 'since' expects an ISO timestamp, and explaining the behavioral effect of mark_read. This adds meaningful usage 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?

The description clearly states the verb 'Pull' and resource 'fired events from your subscription feed'. It specifies returning most recent alerts with details like source and citation_uri. This distinguishes it from sibling tools like fetch_feed or read_feed which may operate on different feed types.

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 polling is fine and provides an alternative URL for scripts, but does not explicitly guide when to use this tool versus other sibling tools like fetch_feed, read_feed, or list_feeds. The context for when to use is implied but not directly stated.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds critical behavioral details: fans out to multiple sources with fallback logic, explains soft-fail for USPTO, and specifies return structure.

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

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

Description is detailed but every sentence adds information. It is front-loaded with examples and uses clear structure. Slightly long but justified by 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?

For a complex tool with no output schema, the description thoroughly covers functionality, sources, fallback, date formats, and return structure. Combined with good annotations, it 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?

Input schema covers all three parameters with descriptions. Description adds value by explaining the tool's behavior with parameters, including date format examples and the meaning of 'since' in 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?

The description clearly states it's a change feed for a company within a time window, with examples like 'what's new with X'. It explicitly distinguishes from sibling entity_profile, which is for 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?

Provides concrete example queries and explicitly advises to use entity_profile for static profile needs, offering a clear alternative and 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?

Annotations indicate mutability (readOnlyHint false), safety (destructiveHint false), and idempotence (idempotentHint true). Description adds that it's a key-value store scoped by identifier, with 24-hour retention for anonymous sessions. 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?

Four sentences, front-loaded with purpose, then usage, then behavioral details, then sibling pairing. No wasted words; every sentence adds value.

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

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

Given 2 required params, no output schema, and simple type, the description fully covers purpose, usage, behavior, persistence, and integration with siblings. No gaps.

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

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

Input schema covers both key and value with descriptions (100% coverage). Description provides example key formats and value types but doesn't add significant 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?

Clearly states the tool saves data for reuse later, with specific verb 'Save data' and resource 'data the agent will need to reuse later'. Provides examples (resolved ticker, target address) and distinguishes from siblings (recall, forget) by name.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward'. Mentions alternatives: 'Pair with recall to retrieve later, forget to delete'. Also explains persistence differences based on authentication.

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, and destructiveHint=false, covering safety. Description adds behavioral context by noting that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups, without contradicting annotations.

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

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

Well-structured: begins with example queries, states purpose, then details supported types and returns. At roughly 100 words, every sentence adds value, though some slight redundancy exists (e.g., repeating 'supported types'). Still efficient and front-loaded.

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

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

Despite lacking an output schema, the description fully explains what is returned for each entity type (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). Covers input formats and disambiguation, making the tool's operation complete for its purpose.

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

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

Schema coverage is 100% (both parameters described). Description enriches both parameters: for 'type', it lists the two enum values ('company', 'drug') and explains what each returns; for 'value', it provides specific examples (ticker, CIK, name for company; brand or generic name for drug) and clarifies accepted formats, far exceeding 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 the tool resolves user-spoken names to canonical/official identifiers required by other tools. Begins with concrete example queries ('What's the ticker for...'), specifies the verb 'resolve' and resource 'name to ID', and differentiates from siblings by positioning itself as the first step when an ID is needed.

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 FIRST whenever you have a name but need an ID.' This provides clear context for when to use the tool. Does not mention explicit exclusions or alternatives, but the direction is unambiguous.

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?

Describes probing each entity with ai_visibility_check, ranking, and output structure (score, confidence, signal density). Complements readOnly/ idempotent annotations with actionable behavioral details.

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

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

Three sentences front-loaded with core purpose, then details and use case. No filler, every sentence adds value.

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

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

Fully explains input, process, output format, and use case. No output schema, but return structure is described adequately.

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

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

Adds significant meaning beyond schema: explains entities ordering, default model, API key usage, context disambiguation. Schema coverage is 100%, but description enriches with examples and narrative.

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

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

Clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them, and surfaces most/least recognized. Differentiates from sibling ai_visibility_check by emphasizing multi-entity comparison.

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

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

Provides context for use: competitive AI-marketing audits with an example. Implicitly distinguishes from single-entity check (ai_visibility_check) but does not explicitly state when not to use.

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

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

Annotations already declare safe read-only behavior; description adds valuable behavioral details: fan-out to two services, partial failure with sources_failed field, and bundlephobia's first measurement delay (5-30s). 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 reasonably concise given the complexity; front-loads purpose and covers edge cases (scoped packages, default version, partial failures). Each sentence adds value, though slightly longer than minimal.

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

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

Despite no output schema, the description lists all return fields (summary block, per-advisory detail, links, alternative versions) and covers edge cases (scoped packages, default version, timing, ecosystem limits). Complete for effective 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% with descriptions for both parameters. Description adds minor context (scoped packages accepted, version default) but does not significantly expand beyond what schema provides, meriting 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 specifies a concrete composite check for npm packages covering license, advisories, version history, and bundle size. It clearly distinguishes from siblings by stating the NPM ecosystem focus and referencing specific services (deps.dev, bundlephobia).

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

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

Explicitly states when to use ('is X safe / popular / small') and notes that PyPI/Maven etc. are handled via deps.dev:version directly. Provides context on partial failures and timing, guiding agent 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral details: uses 'BGE-base-en embeddings + cosine over 500-char overlapping windows', has a '200K chars' cap with truncation and flagging, and returns 'character offsets' for verification. No contradiction with annotations.

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

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

The description is three sentences, dense and front-loaded with core purpose. Every sentence adds unique value. Minor opportunity: could combine second and third sentences slightly, but no waste.

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

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

Despite no output schema, the description fully explains what the tool returns: 'top-N passages with character offsets and similarity scores'. It also covers edge cases (truncation) and pairing context. For a tool with 3 params and no output schema, this is complete and actionable.

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

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

Input schema covers all 3 parameters with descriptions (100% coverage), so baseline is 3. The description adds value by giving concrete examples for the 'query' parameter ('supply-chain risk', 'fiscal year 2024 revenue') and specifying that 'text' is 'the document text you already pulled' and 'limit' default and range. Slight enrichment 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 verb 'semantic search' and the resource 'inside a fetched record'. It distinguishes from siblings by explicitly mentioning the paired tool 'ask_pipeworx_grounded' and contrasting use cases (record too big for prompt). The specificity of 'INSIDE a fetched record' and the detailed use case make it highly clear.

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: 'when the record is too big to cram into the prompt'. It provides alternatives: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages'. It also explains the benefit: 'saves context, returns only the passages that matter, and every passage carries an offset'. This is exemplary guidance.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description discloses behavioral traits: required authentication, subscription id return, delivery channel constraints (email, SMS with cap, webhook signing secret one-time), and auto-disable for webhooks. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose, followed by structured details on types, delivery, and constraints. It is slightly lengthy but every sentence adds essential information. Could benefit from bullet points for easier scanning, but still 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 (multiple types, delivery channels, authentication requirement), the description covers all necessary aspects: required account, type-specific parameters, delivery options with constraints, and return value (subscription id). No output schema exists, but the return info is 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 the description adds significant value by providing concrete examples for each type's params and clarifying constraints for delivery (e.g., SMS phone must be verified, webhook requirements). This goes beyond the schema's 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's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (create), resource (subscription), and includes supported types with examples. It effectively distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

The description provides clear context: requires a Pipeworx OAuth account, explains supported types with concrete params, and details delivery channels. It stops short of explicitly stating when not to use this tool versus alternatives, but the sibling list and usage context imply differentiation.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds behavioral context by stating it returns example questions with exact tool shapes from the live catalog, implying dynamic but safe operation. This adds value 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 fairly long but well-organized, using parentheses and lists to present examples compactly. It front-loads the core purpose and avoids redundancy. Every sentence adds value, though slight trimming could improve 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 (0 required params, no output schema), the description fully explains its return value (category-bucketed example questions with tool shapes) and when to use it. It also mentions learning about meta-tools, making it contextually 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?

The input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds meaning by explaining the topic parameter with concrete examples (e.g., 'finance', 'pharma') and the effect of omitting it (cross-category spread). This enriches the schema's minimal 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 is the onboarding entry point for agents to learn what Pipeworx can do. It uses specific action verbs like 'returns category-bucketed example questions' and 'use this FIRST'. It distinguishes from siblings like ask_pipeworx by focusing on suggesting questions rather than executing them.

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 the agent when to use this tool ('when you do not yet know what Pipeworx can do') and how to call it with or without the topic argument. It also suggests using it to learn about meta-tools, providing clear context and alternatives.

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

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

Annotations indicate idempotent and non-destructive; description adds ownership constraints and explains deactivation instead of deletion, 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?

Two concise, front-loaded sentences 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?

For a simple one-parameter tool, the description fully covers purpose, behavior, and constraints without needing 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 a clear description for the 'id' parameter; the description adds little beyond reiterating the ID's source.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription', and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description specifies ownership enforcement and deactivation behavior, implying when to use, but lacks explicit when-not or alternative 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds value by detailing the return structure (verdict types, structured form, citation, percent delta) and the internal process (replacing multiple calls). No contradictions or missing behavioral traits are evident.

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

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

The description is front-loaded with the core purpose and includes multiple examples, making it efficient. While it is moderately long, every sentence adds value—from use-case phrasing to domain scope and output details. It strikes a good balance between conciseness and completeness.

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

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

Given the simple input schema (one parameter with full coverage) and strong annotations, the description is complete. It covers the type of claims accepted, the domain, the output verdicts, and the citation format. No gaps remain; the tool is fully contextualized 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?

With 100% schema description coverage, the baseline is 3. The description adds significant meaning beyond the schema by providing concrete examples of acceptable claims (e.g., 'Apple's FY2024 revenue was $400 billion') and clarifying the natural-language nature, enhancing the parameter semantics.

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

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

The description clearly states the tool's purpose as natural-language claim verification against authoritative sources, provides explicit examples of user intents, and specifies the domain (company-financial claims for public US companies). It distinguishes itself from siblings by stating it replaces 4-6 sequential calls, making the purpose highly specific.

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 the domain limitation (v1 supports company-financial claims). While it doesn't explicitly state when not to use or list alternatives for non-financial claims, the context signals and sibling tools list provide enough implicit guidance.

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