Gnews

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds details: probes multiple models, returns per-model data, and requires API key for Anthropic. No contradictions. Could mention rate limits or return format more explicitly, but overall good.

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, covering default model, optional Anthropic, return format, and use cases. No redundant or waste sentences.

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

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

No output schema, so description appropriately mentions return structure per-model (score, confidence, signals, raw_response) plus combined view. Notes use cases but omits error handling or edge cases. Sufficient for a simple tool with well-documented parameters.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by providing examples for 'entity' and 'context' (e.g., 'Pipeworx', 'Boston restaurant') and clarifying that '_apiKey' is needed only for Anthropic. Baseline 3 is appropriate as schema already documents all parameters.

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 probes LLMs for knowledge about an entity and returns visibility scores. It specifies the default model and optional Anthropic probe, differentiating it from siblings like entity_profile or deep_research which do not focus on AI visibility scoring.

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

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

Description provides clear usage contexts (AI-marketing audits, pre-launch checks, competitive monitoring) and explains the default model vs. Anthropic with API key. However, it does not explicitly exclude alternative tools or contrast with similar siblings like scan_competitor_ai_presence.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds context about routing to 4,774 tools and returning structured answers with citation URIs, which is helpful beyond annotations.

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

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

The description is well-structured with actionable guidance and examples, though slightly verbose. It front-loads key advice and maintains clarity throughout.

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

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

Given no output schema, the description explains return format (structured answer with citation URIs) and covers usage scenarios comprehensively. No gaps.

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

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

Schema coverage is 100% and describes the question parameter with aliases. The description adds clarity on the aliases and natural language input, but the schema already covers the parameter.

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

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

The description clearly states it answers factual questions using authoritative structured data, distinguishing itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs to prefer over web search, provides examples of when to use, and explains when to step up to sibling tools for more grounded or broad queries.

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

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

Description adds significant behavioral context beyond annotations: costs one extra LLM call vs ask_pipeworx, returns explicit refusals with reasons, and extracts answers only from tool results. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Description is well-structured with a clear opening statement, followed by process details, use case guidance, and trade-off. Every sentence serves a purpose, though slightly verbose. Could be tightened without losing meaning.

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

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

Given complexity (tool selection, extraction, refusal handling) and no output schema, the description fully explains input format, process, return structure with example fields, and refusal reasons. No gaps for the agent to misuse.

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

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

Schema coverage is 100% (all parameters are aliases for 'question'). Description describes the 'question' parameter as accepting natural language and lists aliases, adding clarity over the schema alone. Baseline 3, plus extra value from alias details.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explains the process of tool routing, data fetching, and answer extraction using only tool results. It distinguishes itself from sibling 'ask_pipeworx' by noting the extra LLM call and specific use cases.

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

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

Explicitly provides when to use (answers that will be quoted/cited/acted on, high-stakes domains like financial/legal/medical) and when not to (prefer ask_pipeworx for casual lookups). Includes concrete examples.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: fan-out examples, response shapes, resolver contract, parent event extractor, news fields handling, safety measures (low-confidence short-circuit), market closed/inactive handling, wide-spread illiquidity warnings, and resolution-rule risk. 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 well-structured with capitalized section headings (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). It front-loads the core purpose but includes some verbose details like exhaustive classifier list. Every sentence adds value, 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 the complexity (3 params, no output schema), the description is very complete. It covers resolution mechanics, edge cases, response fields, safety checks, and integration with other services. No significant gaps; all necessary behavioral context is provided.

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 parameters are already documented. The description adds context on how parameters affect behavior (e.g., depth 'quick' vs 'thorough', include_raw detailed explanation). It does not repeat schema but provides usage nuance, slightly improving over baseline 3.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outlines the process (resolve, classify, fan out, return evidence). It distinguishes from siblings by focusing on single-bet research, unlike tools like polymarket_edges.

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

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

Explicit usage scenarios are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It explains when to inspect fields (low-confidence matches) and mentions depth parameter options. However, it does not directly contrast with sibling tools, and there is no guidance on choosing between 'quick' and 'thorough' depth.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive behavior. The description adds transparency by detailing that it pulls latest 10-K data from SEC EDGAR/XBRL, correctly handles off-calendar fiscal years, returns sorted results, and includes citation URIs. No contradictions with annotations.

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

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

The description is a single focused paragraph that front-loads common query phrases, then explains functionality. It covers all key points without verbosity, though a slightly more structured layout (e.g., separating company and drug behavior) could improve readability.

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 the absence of an output schema, the description fully explains what the tool returns: paired data with citation URIs, results sorted by primary metric. It covers both entity types and their respective data sources, making the tool's behavior complete and predictable for an agent.

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

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

Schema coverage is 100%, with both parameters described. The description adds value by explaining that 'values' should be tickers/CIKs for companies and drug names, with example data sources (10-K revenue/net income, FAERS adverse events). However, the schema already includes enums and descriptions, so the added semantic lift is moderate.

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

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

The description explicitly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It provides common query phrases ('Compare X and Y', 'which is bigger') and clearly distinguishes it from sequential single-pack lookups, making the intent unmistakable.

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

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

The description includes the directive 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' offering explicit guidance on when to use this tool over alternatives. It also explains what each type ('company' vs 'drug') returns, further clarifying 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?

The description discloses key behavioral traits beyond the annotations: account requirement (free/paywalled depth), decomposition into facets, parallel execution, expected timing (15-60s), output format (findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[]), and that it is NOT open-web search. Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds 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 appropriately concise for a complex tool. It is front-loaded with the most critical information (account requirement and alternative for non-signed-in users). Every sentence adds value: what it does, how it works, when to use/avoid, timing. Despite its length, it is well-structured with no redundancy.

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

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

Given 2 parameters and no output schema, the description provides complete context for an AI agent to decide when and how to use the tool. It explains the output format (findings packet with gaps), timing, constraints, and prerequisites (account). No additional information is needed for decision-making.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra context: depth enums are explained in terms of facet count ('quick=3, standard=5 (default), thorough=8 (paid plans)'), and the question parameter is described as 'natural language. Broad/multi-part is fine'. This provides clarity beyond the schema descriptions, justifying a score above 3.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1242 STRUCTURED data sources...decomposes your question into focused facets, routes each to the right one of 4,774 tools IN PARALLEL'. It distinguishes from siblings like ask_pipeworx (single lookup) and specifies what kind of questions it handles ('broad/multi-part questions over structured data'). The verb 'research' and resource 'Pipeworx's structured data sources' are specific and unambiguous.

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

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

The description provides explicit usage guidance: when to use (broad/multi-part questions), when not to use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS...prefer ask_pipeworx'), and alternatives (ask_pipeworx for single lookup and current news). It also notes that deep_research returns 'mostly empty gaps[]' for topics not in the structured catalog, helping the agent avoid inappropriate usage.

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

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

Adds value beyond annotations by explaining it returns top-N relevant tools with full schemas, ready to call 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?

Single well-structured paragraph with front-loaded purpose. Compact list of domains and clear call-to-action. No wasted words.

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

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

Given no output schema, description adequately explains what the tool returns (names, descriptions, schemas) and when to use it. 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% with detailed descriptions and examples. Description restates aliases and reinforces purpose, adding marginal value beyond schema.

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

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

Description clearly states the tool discovers tools by describing data or task. It lists specific domains and distinguishes itself as a meta-tool to be called first among siblings.

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 specifies when to use ('browse, search, look up, discover what tools exist') and advises calling it first when many tools are available. Does not explicitly state alternatives but context implies it's for exploration.

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 discloses behavioral traits beyond annotations: parallel fan-out across multiple APIs, detailed return fields, patent API sunset warning, and idempotent/read-only nature confirmed. No contradiction with annotations.

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

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

Description is detailed but front-loaded with examples and purpose. Every sentence adds value, though slightly long. Structure is logical: examples, purpose, usage, sources, returns, parameter notes.

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

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

Given no output schema, description covers all return data (cik, filings, fundamentals, patents, news, LEI) and mentions potential failure in patents. Contextual completeness is high for a composite tool with multiple data sources.

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?

Description adds meaning over schema by providing examples ('AAPL', '0000320193'), specifying that only 'company' type is supported, and explicitly stating names are not allowed. Schema already describes params well but description enriches understanding.

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

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

Description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call', lists specific data sources and return fields, and contrasts with chaining single-pack lookups, distinguishing it from siblings like compare_entities and 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 'ALWAYS PREFER over chaining single-pack... when user asks for holistic view' and clarifies when to use resolve_entity for names. Provides clear usage context.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but 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?

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

For a simple one-parameter tool with no output schema, the description is complete: it states action, usage context, and relationships to siblings.

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 does not add additional meaning beyond what the schema already provides for the 'key' parameter.

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

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

The description clearly states 'Delete a previously stored memory by key', uses a specific verb and resource, and distinguishes from siblings by mentioning 'Pair with remember and recall.'

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and pairs 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?

The description adds significant behavioral context beyond annotations: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also notes the output is 'a single text blob ready to drop at site-root/llms.txt'. 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 two concise sentences plus a bullet list of use cases, all front-loaded with the primary action. No redundant information.

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

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

Given the simple tool (2 params, no output schema), the description fully explains input, process, and output format. The use cases cover why and when to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the 'url' parameter by mentioning 'for any URL' and 'fetches the page', but does not add meaning beyond schema for 'max_links'.

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 the verb 'generate', the resource 'llms.txt file', and the context 'for AI crawlers'. It clearly distinguishes from sibling tools like 'ai_visibility_check' by focusing on the standard llms.txt markdown format.

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 concrete use cases ('getting a client's site indexed', 'drafting for own project', 'auditing competitor'), providing clear context. However, it does not explicitly state when not to use or mention alternative tools.

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

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

Annotations already declare read-only and idempotent nature. Description adds that it returns specific fields and scopes to caller's subscriptions, providing useful 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 sentences: first describes action and output, second gives usage advice. Front-loaded, 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?

Sufficient for a simple list tool with one optional parameter. Could mention pagination but not critical given open-world hint and typical use case.

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

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

Schema covers the single parameter (include_inactive) with 100% description coverage. Description does not elaborate on the parameter, so baseline 3 applies.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates return fields, distinguishing it 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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel', indicating when to use and implying alternatives.

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

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

The description discloses rate limits (5 per identifier per day), cost (free, no quota consumption), and processing (team reads digests daily). Annotations are neutral (readOnlyHint=false, destructiveHint=false) and the description adds valuable behavioral context without contradiction.

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

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

The description is a single paragraph but packs essential information efficiently. It could be slightly more structured (e.g., bullet points) but remains concise and front-loaded with the core purpose.

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

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

Given the absence of an output schema, the description covers all necessary contextual information: input constraints, rate limits, cost, processing details, and explicit use cases. It is fully complete for an agent to correctly select and invoke the tool.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds minimal extra meaning beyond the schema, only briefly mentioning the type values. Baseline of 3 is appropriate since the schema already handles parameter semantics adequately.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature, data_gap, praise) and explicitly distinguishes from siblings by being the only feedback tool among 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 provides explicit guidance on when to use the tool for each feedback type and includes a 'don't' instruction (not pasting end-user prompts). However, it omits explicit mention of alternatives or when not to use it, which would elevate it to a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial beyond: data source (CF analytics-engine), privacy (no PII), structure (pack, tool, count), and caching behavior (5min-1h). No contradictions.

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

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

Three succinct paragraphs: (1) what it returns, (2) three bullet-like use cases, (3) technical details. Every sentence adds value; no redundancy. Perfectly front-loaded with the core functionality.

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, no output schema, and rich annotations, the description covers purpose, use cases, parameter behavior, data origin, privacy, and caching. No gaps 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% with a single enum parameter. The description adds value by explaining the trade-off between window lengths ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which helps agents choose the correct value.

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

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

The description clearly states it returns top tools, top packs, and total call volume over recent windows. It uses specific verbs ('returns') and resources ('tools, packs, volume'), distinguishing it from siblings like 'discover_tools' which likely focuses on discovery rather than trend aggregation.

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?

Three explicit use cases are provided (discovering hot data, confirming canonical choice, aligning with agent needs). It also explains window trade-offs (shorter for hot, longer for steady-state). While no explicit when-not or alternatives, the context is clear enough for selection among 30+ siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: explains algorithms (monotonicity, partition checks), semantic anchor (Jaccard similarity), partition filter, fill check against CLOB depth, and the response structure. 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 thorough but somewhat verbose, with 7+ sentences including implementation-like details (e.g., 'SEMANTIC ANCHOR: ... Jaccard similarity'). While front-loaded with the main purpose, it could be more concise. The verbose nature detracts from optimal conciseness.

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

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

Given the tool's complexity, no output schema, and rich annotations, the description is remarkably complete. It explains all three modes, the algorithmic approach, the response structure (opportunities array with fields, partition_check in event mode), the fill check, and the limitation for thin legs. It also references a sibling tool for custom sizing.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context beyond the schema: explains that event accepts slugs or full URLs, that topic is a seed question, and provides examples. It also details the behavior associated with each parameter (single-event vs cross-event). This justifies a score above baseline 3.

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and contrasts with sibling tools like polymarket_fill_risk, making its specific purpose very 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?

Explicit guidance is provided: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning).' It also warns when not to trade ('do not trade it' if realizable edge ≤0) and suggests a sibling tool ('For custom sizing use polymarket_fill_risk').

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 as true. The description adds significant detail: model families, caching at KV level for 1 hour, diagnostics for empty segments, and tradeable-edge knobs. 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 detailed but well-structured with sections on model families, knobs, and response format. It is front-loaded with purpose and uses examples. While long, every part serves a purpose given 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?

Despite no output schema, the description fully explains the response structure: by_segment, fed_candidates, _diagnostics. It covers edge cases (Fed data caveat, caching, diagnostics for empty segments). Complete for a read-only data retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining tradeable-edge knobs (min_liquidity, max_spread_pp) and min_partition_leg_kelly logic beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb-resource combination and distinguishes itself from siblings by focusing on Pipeworx data disagreement.

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

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

The description provides clear context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains knobs and filters but does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description goes beyond annotations by detailing the response structure (tracked, expired, snapshot_dates), explaining the meaning of gaps and decay computation. It adds rich behavioral context without contradicting the readOnly and idempotent hints.

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 the purpose upfront, followed by response details. While slightly verbose, it efficiently conveys necessary information without redundancy.

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

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

Given the complexity of the response (time-series, multiple arrays) and the absence of an output schema, the description thoroughly explains all return fields and constraints, making it complete for effective 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?

The input schema already covers both parameters with descriptions. The description adds minor details (e.g., 'max 30' vs. 'clamp 2-30') but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry. It answers a specific question about edge freshness and 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?

The description provides context on when to use the tool, such as comparing fresh vs. old edges, and mentions limits like the 60-day TTL. However, it does not explicitly exclude alternative tools or provide direct usage scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: walking the ladder, returning top_of_book/vwap/slippage/verdict, and warning about thin books and directional risk. This complements the annotations without contradiction.

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

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

The description is comprehensive but slightly verbose. It is front-loaded with the core purpose and has clear sections for single-market and basket modes. However, some redundancy exists (e.g., repeating 'realizable vs theoretical'). Still well-structured and 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 the tool's complexity (two modes, multiple return fields, no output schema), the description covers all necessary information: input requirements, behavior, return fields, and risk warnings. It fully compensates for the lack of output schema by detailing the output fields and their meanings.

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

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

Schema coverage is 100% with descriptions for each parameter. The description enhances this by explaining how parameters behave in different modes (single-market vs basket), default behavior for 'side' in basket mode, and interpretation of 'size_usd' for sell vs buys and basket settlement notional. Adds meaning beyond the schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It specifies the verb (check, fill risk) and resource (Polymarket order-book depth), and differentiates from siblings like polymarket_arbitrage and polymarket_edges by being a prerequisite check.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns against what not to do ('partial basket fills convert an arb into an unhedged directional position'), providing clear context and exclusions.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, nondestructive behavior. The description adds rich behavioral detail: it explains the two compatibility_warning scenarios, temporal alignment, skipped_cross_type/subtype counters, and the caveat that real spreads are rare. No contradiction with annotations.

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

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

The description is well-structured: definition, modes, response format, safety fields. It is relatively long but every sentence contributes useful information. Minor verbosity in the safety fields section could be tightened, but overall it is efficient and front-loaded with the key 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 adequately covers the response structure (leg prices, spreads, safety fields) and their meaning. It explains compatibility_warning and temporal_alignment in detail. However, it omits specific field names like matched_pairs count or top_spreads_pp array, which could help the agent parse output. Still, it is fairly complete for a complex tool.

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

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

Schema coverage is 100%, and the description adds significant value: it lists all topic shortcut values, provides examples for explicit tickers, and explains that explicit parameters override topic-mapped sides. This goes beyond the schema alone, making parameter semantics very clear.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage by focusing on the cross-venue aspect. It specifies two modes (topic shortcuts and explicit tickers), making its purpose precise and unambiguous.

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

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

The description explains when to use each mode (topic vs explicit) and warns that most pre-mapped topics return compatibility warnings, discouraging blind use. It does not explicitly compare to sibling tools but provides enough context for appropriate usage, such as checking compatibility_warning and temporal_alignment.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping ('anonymous IP, BYO key hash, or account ID') and pairing hints with remember/forget, which is valuable beyond annotations.

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

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

Three compact sentences with no unnecessary words. Front-loaded with action, includes scoping and pairing, all essential information.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains input behavior, scoping, and relationship with siblings. No gaps remain.

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

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

Schema coverage is 100% with description 'Memory key to retrieve (omit to list all keys)'. Description reinforces this and clarifies omit behavior, adding meaning beyond the schema.

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

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

Description clearly states it retrieves or lists saved values, with specific verb ('retrieve', 'list') and resource ('value previously saved via remember'). Distinguishes from siblings 'remember' and 'forget'.

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

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

Provides guidance on when to use (look up previously stored context) and how to use (omit key to list all). Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds crucial context: setting mark_read:true flags events as read, affecting subsequent calls, and describes returned fields (source, citation_uri, raw payload). No contradiction with annotations.

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

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

The description is concise and front-loaded with the main action. It efficiently conveys key information in a single paragraph without unnecessary verbosity.

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 5 parameters, no output schema, and no nested objects, the description adequately covers what the tool returns (source, citation_uri, raw payload), how filtering works, and the mark_read behavior. It provides sufficient context for 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?

All 5 parameters are covered in the schema (100% coverage). The description adds value by providing examples (e.g., 'sec_8k' for type), explaining the effect of mark_read, and clarifying that since expects an ISO timestamp.

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

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

The description states clearly that the tool 'pull[s] fired events from your subscription feed' and returns recent alerts with specific fields. It distinguishes itself from siblings by focusing on retrieving events rather than managing 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 mentions that polls work fine and provides an alternative HTTP endpoint for scripts and dashboards, giving context on when to use the tool versus the direct API. However, it does not explicitly contrast with sibling tools like list_subscriptions.

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

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

Adds significant behavioral context beyond annotations: non-blocking fallback (GDELT→GNews), soft-fail for patents, parallel calls, and return structure (changes[], total_changes, citation URIs). No contradiction with readOnlyHint and idempotentHint.

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

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

Single paragraph, but effectively front-loaded with the main purpose. Information dense but clear. Minor room for improvement in structural organization.

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 (multiple sources, fallbacks, parameter options, and sibling distinction), the description is highly complete. Covers edge cases (rate limits, sunset, soft-fail) and outlines return structure despite no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that value can be ticker or CIK, since accepts ISO or relative shorthand, and type is only 'company'. Also provides recommended values for since.

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

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

The description clearly states it is a change feed for a company covering SEC filings, news, and patents. It uses specific verbs like 'fans out' and explicitly distinguishes from sibling tool 'entity_profile', earning a top score.

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 guidance on when to use (e.g., 'What's new with X'), what it does (sources, fallbacks), and when not to use (referring to entity_profile). Also explains the 'since' parameter with examples like '30d' or '1m'.

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 include idempotentHint=true and no destructive hint. The description adds behavioral context beyond annotations: scoping by identifier, persistence duration (24 hours for anonymous, persistent for authenticated). 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 four sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, behavioral details, scoping, and links to related tools. It 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% with descriptions. The description adds examples of key-value pairs (e.g., 'subject_property', 'user_preference') but does not add new constraints or syntax details 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 specifies the action (save), resource (data to reuse later), and scope (key-value pair scoped by identifier). It distinguishes itself from siblings like recall and forget.

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

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

The description provides explicit examples of when to use (resolved ticker, target address, etc.) and mentions related tools (recall, forget). It does not explicitly state when not to use, but the context is clear for a memory 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 indicate read-only, idempotent, and open-world behavior. The description adds value by noting internal cascading through multiple endpoints and describing the output structure (ticker, CIK, RxCUI, citation URIs). No contradictions.

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

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

The description is informative and well-structured, starting with examples and then detailing supported types. It is not overly verbose, but could be slightly more concise by combining the example list.

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 supporting multiple entity types and no output schema, the description fully explains the return values (ticker, CIK, RxCUI, citation URIs) for both types. No additional information seems necessary.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing example inputs for each type (e.g., 'AAPL', 'ozempic') and clarifying acceptable formats, which aids the agent in parameter selection.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples like 'find the CIK'. It distinguishes itself from sibling tools by focusing on name-to-ID resolution.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear usage guidance. It does not explicitly state when not to use or mention alternatives, but the context is strong.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context: it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. This adds value beyond annotations without contradiction.

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

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

Three sentences: purpose, method, use case. Front-loaded with the key verb and differntiation. 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?

No output schema, but the description clearly states the return type (ranked list with score, confidence, signal density). It explains the role of the first entity and covers optional parameters. Complete for a comparison tool.

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

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

Schema description coverage is 100%, so the schema already documents all 4 parameters. The description mentions context as shared context and the inner tool name, but does not add significant new 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 the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It distinguishes from sibling tools like ai_visibility_check by focusing on multiple entities.

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 a concrete use case (competitive AI-marketing audits) and an example question. It implies when to use (multiple entities) but does not explicitly state when not to use or mention alternatives like ai_visibility_check for single entities.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. 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 paragraph but is concise and front-loaded with the main purpose. Every sentence adds value, covering use cases, limitations, return structure, and failure behavior. 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?

Without an output schema, the description thoroughly explains what is returned (summary block with specific fields, per-advisory detail, links, alternative versions) and handles failure behavior. It is complete for a composite tool.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning by stating that scoped packages are accepted and that version defaults to latest when omitted, providing context beyond the schema.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, combining data from deps.dev and bundlephobia. It specifies the exact use case ('should I add this npm package to my project') and distinguishes from siblings, which focus on other domains.

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

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

The description explicitly says when to use ('whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'') and provides limitations ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This gives clear guidance on 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, covering safety and idempotency. The description adds context about global scope and return fields but does not disclose additional behaviors like rate limiting, pagination, or auth requirements beyond what the schema indicates. This is adequate but not exceptional.

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

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

The description is two sentences long, each adding value. The first sentence states the main action with examples, the second lists return fields and supported filters. No redundant or extraneous information, achieving maximum 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?

With 5 parameters (2 required) and an output schema, the description covers the core functionality and return structure. It does not mention pagination or the 'max' parameter's role, but the schema fills this gap. Overall, it is sufficiently complete for an agent to understand the tool's capability, though a mention of pagination would improve it.

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

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

Schema coverage is 100% with each parameter described. The description mentions keyword and filters but adds little beyond the schema's own descriptions. It provides example values but no deeper semantics. Baseline 3 is appropriate as the schema already carries the semantic load.

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 action ('Search global news articles by keyword') and lists specific return fields (title, description, etc.). It also provides example keywords and mentions language/country filters, making the purpose unambiguous and distinguishing it from siblings like 'top_headlines' which likely has a different focus.

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

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

The description implies usage context (searching by keyword) but does not explicitly state when to use this tool versus siblings like 'top_headlines' or other search tools. No when-not or alternative recommendations are given, leaving the agent to infer the appropriate use case.

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, idempotentHint, etc., but the description adds significant behavioral details: embeddings model (BGE-base-en), sliding window size (500-char overlapping), character limit (200K), truncation behavior, and output format (passages with offsets and scores). No contradiction.

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

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

Three sentences, each earning its place. The most critical information (semantic search inside record, use case, technical details) is front-loaded. 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?

Despite no output schema, the description explains return values (top-N passages with character offsets and similarity scores) sufficiently. The tool complexity is moderate and all key aspects are covered.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing natural-language query examples and clarifying the default limit and range, going beyond the schema descriptions.

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

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

The description clearly states it does semantic search inside a fetched record, using verbs like 'search inside' and specifying the resource. It distinguishes from siblings by naming a complementary tool (ask_pipeworx_grounded) and explaining the workflow.

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: 'when the record is too big to cram into the prompt.' It also explains how it saves context and pairs with ask_pipeworx_grounded, providing clear alternatives.

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

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

Beyond the annotations (which indicate readOnlyHint=false, idempotentHint=true, etc.), the description adds important behavioral details: subscription persistence, delivery channel limits (10/day SMS cap), webhook auto-disable after 10 failures, and requirement for phone 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 structured with a clear opening sentence, followed by prerequisites, supported types, and delivery details. While slightly lengthy, every sentence contributes essential information. It is front-loaded with the 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 the tool's complexity (three parameters with nested objects, no output schema), the description is remarkably complete. It covers input requirements, behavioral constraints, return value (subscription ID), and delivery channel behaviors, leaving no critical gaps.

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

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

The description significantly expands on the input schema by providing concrete examples for each type's params, clarifying delivery channel requirements and constraints (phone verification, email validation, webhook signing). All parameters are covered, adding substantial semantic value beyond the schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It specifically differentiates from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

The description specifies prerequisites (requires Pipeworx OAuth account) and provides examples for each subscription type. However, it does not explicitly state when not to use this tool or suggest alternatives, such as recent_alerts for pulling existing alerts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the output format (category-bucketed examples with tool+argument shapes) and the behavior with/without topic argument, 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?

The description is long but well-structured, front-loading common user questions. Every sentence adds value, though some repetition ('what can I ask') could be trimmed slightly. Still highly 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?

Given the tool's simplicity (one optional parameter, no output schema), the description covers all needed context: what it returns, when to use, how to call, and examples. No gaps.

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

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

Schema coverage is 100%, but description adds meaning by listing example topic values and explaining the effect of omitting topic (full spread). It also maps the parameter to specific categories, clarifying its semantic scope.

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

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

The description uses a specific verb ('returns') and resource ('category-bucketed example questions'), clearly distinguishing it from sibling tools as an onboarding entry point. It includes common user intents ('what can I ask', 'give me ideas') and positions the tool as a first-use resource.

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

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

Explicitly states when to use ('Use this FIRST when you do not yet know what Pipeworx can do') and provides example user queries. It also hints at alternatives (meta-tools) and gives usage options (no args vs. topic filter).

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 readOnly, idempotent, open world hints. Description adds context: requires API key, returns up to 100 articles with specific fields. No contradictions.

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

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

Two sentences, front-loaded with main purpose, no wasted words. Highly efficient.

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

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

Given full schema coverage and presence of output schema, the description covers the API key requirement, filter options, and return fields. Minor gap: no explicit mention of default values.

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 3. Description lists filter options but doesn't add meaning beyond schema descriptions of parameters.

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

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

Clearly states it fetches top headlines from GNews with optional filters. However, among siblings like 'search_news', it doesn't explicitly differentiate, slightly reducing clarity.

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?

Implies usage for getting top headlines with optional filters, but no explicit when-not-to-use or alternatives mentioned. Sibling 'search_news' could be for specific queries, but not addressed.

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 behavior. The description adds value by explaining that the row is deactivated (not deleted) and historical events remain available via recent_alerts. 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 consists of two sentences: the first immediately states the core action, and the second adds ownership and behavioral context. No wasted words, and information is 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?

Given the tool's simplicity (single parameter, idempotent, non-destructive), the description sufficiently covers what happens (deactivation, not deletion) and ownership constraints. It does not specify the return value, but this is minor for a cancellation action.

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

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

The schema already describes the single parameter 'id' as a UUID returned by subscribe, and the description merely says 'by id.' With 100% schema coverage, the description adds no new semantic details 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 'Cancel a subscription by id,' which is a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by detailing ownership enforcement and deactivation behavior.

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

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

The description explicitly states 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear context for when to use the tool. While it doesn't mention alternatives, the sibling tools (subscribe, list_subscriptions) imply when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint (all safe). The description adds significant context: it explains the return structure (verdict, extracted form, actual value, citation, percent delta), mentions it replaces multiple sequential calls, and clarifies domain constraints (SEC EDGAR + XBRL, public US companies). 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 moderately long but well-structured: it starts with example queries, states usage, explains domain, then lists return fields. Every sentence adds value, though a slight reduction in redundancy could improve conciseness (e.g., the list of example queries is somewhat repetitive).

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 compensates by listing return fields (verdict, extracted form, actual value, percent delta, citation). It also covers domain limitations (v1, company-financial, public US) and explains that it replaces multiple calls. With one parameter and good annotations, it is fairly complete, though a note about rate limits or error handling would improve it.

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

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

Schema coverage is 100% (only one parameter 'claim' with description). The description enhances understanding by providing examples of valid claim formats (e.g., 'Apple's FY2024 revenue was $400 billion') and clarifying that it's natural-language, which adds value beyond the schema's brief 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 uses specific verbs like 'verify', 'fact check', and 'confirm or refute' with a clear resource: natural-language claim verification against authoritative sources. It includes multiple example query patterns and explicitly states it replaces 4-6 sequential calls, making its role distinct from sibling tools like 'search_news', 'deep_research', or 'entity_profile'.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims for public US companies) and notes 'v1 supports company-financial claims', implying limitations. However, it does not provide explicit when-not-to-use scenarios or direct comparisons to other tools for non-financial claims.

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