Newsapi

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

Annotations already cover the read-only, idempotent, open-world, and non-destructive safety profile. The description adds valuable context: the default model is free (Workers AI Llama-3.3-70b), passing `_apiKey` triggers direct calls to Anthropic billed to the user, and the return format includes per-model {score, confidence, signals, raw_response} plus a combined view. This goes beyond the annotations by disclosing cost implications and output structure, which is essential for an agent to set expectations.

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

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

The description is concise and front-loaded: it opens with the core action and output, then covers the key configuration option (default vs Anthropic), then the return shape, then use cases. Each sentence earns its place with no redundancy, making it an efficient and well-structured description.

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

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

With no output schema, the description compensates by specifying the return structure (score, confidence, signals, raw_response + combined view). It also covers model selection, the optional API key, and application contexts. It does not explain the meaning of 'signals' or 'confidence', but that is not necessary for correct invocation. Given the strong annotations and full parameter coverage, the description is sufficiently complete.

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

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

The input schema has 100% coverage with clear descriptions for all parameters. The description adds meaning by specifying the default model (workers-ai), stating that `_apiKey` is needed only if 'anthropic' is included in `models`, and indicating that omitting `models` uses the default. This relationship between parameters and default behavior is not fully documented in the schema alone.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' This is a specific verb+resource+outcome, which distinguishes it from sibling tools like ask_pipeworx (likely just querying LLMs) and scan_competitor_ai_presence (which may focus on competitor monitoring).

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

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

The description explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model and the optional `_apiKey` for Anthropic, giving clear context for when to use it. However, it does not explicitly state when not to use it or name alternatives, so it falls short of full exclusionary guidance.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds valuable context: routes to 5,578 tools, fills arguments, returns stable citation URIs, and is fast across all tiers. This goes beyond the annotations without contradicting them.

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

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

The description is long but densely packed with necessary information: priority guidance, domain list, usage trigger phrases, examples, and escalation paths. It is front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and structured logically, though some redundancy exists in listing triggers.

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 (many sources, alternatives, and use cases), the description is thoroughly complete. It covers function, scope, examples, and relationships to sibling tools, and even hints at output format (structured answer with citation URIs), which partially compensates for the lack of an output schema.

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

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

Schema coverage is 100% with all aliases documented. The description adds meaningful guidance by providing multiple concrete question examples that illustrate the expected natural language input, enriching the schema's description beyond the simple type definition.

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

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

The description clearly states the tool's function: it routes questions to a large set of verified tools and returns structured answers with citation URIs. It distinguishes itself from siblings by being the default entry point and explicitly naming alternatives (ask_pipeworx_grounded, 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?

Provides explicit guidance: 'PREFER OVER WEB SEARCH' with specific categories, and explains when to step up (grounded for evidence-backed single answer, deep_research for multi-part). It also notes behavior for breaking news, making when-to-use and when-not-to-use very clear.

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

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

Annotations already declare read-only, open-world, and idempotent hints. The description adds valuable context about the beta status, that no candidate is currently active so it matches ask_pipeworx, and that it is a full working router with no fallback. This goes beyond the annotations without contradicting them.

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

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

The description is moderately sized and front-loaded with the key concept (beta router). It efficiently explains current status, usage, and purpose in about four sentences, though it could be slightly tighter. No redundant fluff.

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

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

Given the lack of an output schema, the description compensates by referencing the stable ask_pipeworx's response shape and clarifying operational details like the beta testing pipeline. It adequately covers the tool's role and current state, though it relies on sibling context for full response details.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question'. The description adds no additional parameter details, which is acceptable given the schema's completeness. Baseline of 3 applies because the description does not enhance parameter understanding.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools and arguments. It distinguishes itself from the stable sibling by emphasizing its experimental edge and current identical behavior, making the purpose unambiguous.

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

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

Explicitly instructs to use it 'exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This gives clear when-to-use guidance and implicit exclusion for stable requests, differentiating from the sibling ask_pipeworx.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description reveals the tool's refusal behavior with explicit refusal_reason codes (not_in_source, no_tool_match, tool_error, etc.), the evidence-quote extraction mechanism, and the cost implication (one extra LLM call). It also clarifies that answers are extracted only from tool results, preventing hallucination—details that are not available from the annotations alone and are critical for safe usage.

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

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

The description is well-structured and front-loaded with the core purpose, but it is relatively long (three sentences covering routing, return format, and usage guidance). Each sentence adds meaningful value, and the information is organized logically (what it does, return format, when to use). It is slightly verbose but not excessively so, and the density of information justifies the length. A score of 4 reflects that it is effective but could be tightened to a single paragraph without losing 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?

The description is remarkably complete for a tool with no output schema. It details the success return object (answer, evidence, confidence, source, fetched_at, refusal_reason) and the refusal variant (answer:null, refusal_reason with enumerated values), explains the routing and extraction behavior, and provides usage context. This covers practically every aspect an agent would need to invoke the tool correctly and interpret results, making it highly complete.

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

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

The input schema already documents the required 'question' parameter and lists five aliases (q, text, input, query, prompt) with full descriptions. The tool description does not add any additional parameter semantics beyond what the schema provides—it simply refers to 'natural language' indirectly. Since schema coverage is 100%, the description's lack of parameter text is acceptable, but it also doesn't enhance or clarify the parameter usage beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that routes through 5,578 tools across 1,463 sources, fetches data, and extracts answers only from tool results. It explicitly mentions the return format and refusal mechanism, and differentiates from the sibling 'ask_pipeworx' by noting the extra LLM call and the intended use case for high-stakes reads. This makes the purpose unambiguous and distinct.

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

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

The description explicitly states when to use the tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to ('prefer ask_pipeworx for casual lookups'). It also names the alternative (ask_pipeworx) and explains the cost trade-off (extra LLM call), giving clear decision guidance beyond a simple 'when to use' statement.

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 readOnly/openWorld/idempotent annotations, the description discloses extensive runtime behaviors: parallel fan-out to category-specific data packs, resolver contract with market_match_confidence, parent_event extraction, news fallback flags (_fallback_attempted, retry_after_sec), safety short-circuit on low-confidence matches, status codes for closed/inactive and wide-spread markets, and cancellation-rule risk with EV impact. This is far more than annotations provide.

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

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

The description is long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Every section adds necessary detail for a complex tool, though a slightly more condensed version could improve conciseness.

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

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

With no output schema, the description fully covers return values: result.market fields, result.analysis with edge_pp and kelly_fraction, result.evidence keying, the resolver contract with market_match_score and alternatives, parent_event details, news fallback flags, and blocking statuses for low-confidence or closed markets. It also explains cancellation-rule risk and its EV implications, making it essentially a complete spec.

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

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

Schema coverage is 100%, so the schema already fully documents market, depth, and include_raw. The description reinforces input types (slug/URL/question) and gives examples, but it does not add new parameter semantics beyond what the schema already states. The description's additional detail is about behavior rather than parameter meaning.

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

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

The description opens with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from siblings by specifying input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison), making its role unique among tools like ask_pipeworx or 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 triggers are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when results are blocking or unreliable (low-confidence matches, closed markets). However, it does not name alternative tools for when NOT to use this one, so there's no explicit exclusion guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description goes further by disclosing data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and the return of paired data with citation URIs. This adds substantial behavioral context beyond the structured annotations.

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

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

The description is front-loaded with trigger phrases and usage direction, followed by type-specific behavior and output details. Every sentence earns its place, providing dense, non-redundant information. Despite its length, it remains well-structured and efficient for the complexity of the tool.

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

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

Given the absence of an output schema, the description covers essential return details: data types, sorting, and citation URIs. It also explains critical edge cases like off-calendar fiscal years. However, the exact response structure ('paired data') is somewhat vague, leaving some ambiguity about the precise format the agent will receive.

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

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

Schema coverage is 100% with clear descriptions for 'type' and 'values'. The description enriches the 'type' parameter by specifying exactly what data each enum value retrieves ('company' pull financials, 'drug' pulls adverse-event counts). It also clarifies the values parameter through examples ('AAPL, MSFT' vs 'ozempic, mounjaro'), adding semantic 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 begins with trigger phrases ('Compare X and Y', 'X vs Y') and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call'. It clearly identifies the resource (companies/drugs) and the action (comparison), while distinguishing itself from single-entity lookups by emphasizing 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and lists concrete comparison queries. It also outlines what data is returned for each type (company vs drug), giving clear context for when to invoke this tool instead of 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 readOnly=true annotation, the description reveals it "returns a findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation" and explains the second-hop iteration and contradictions[] behavior. It also discloses latency expectations (15-60s, up to ~90s) and that it is "NOT open-web search," adding valuable context beyond annotations.

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

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

The description is dense but every sentence earns its place, from the account-required warning to latency expectations. It is well-structured with em-dashes and semicolons, front-loading the most critical operational details (account requirement, core purpose) and escalating through advanced behaviors, making it highly usable despite its length.

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

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

With no output schema, the description compensates thoroughly by specifying the return packet's structure (verbatim evidence, confidence, source, fetched_at, citation URI), the gaps[] mechanism, contradictions[], and hop fields. It also covers account prerequisites, differences between depth levels, and usage examples, leaving no obvious gap in understanding for a prospective caller.

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?

Although schema coverage is 100%, the description significantly enriches parameter meaning. It details the depth enum's effects ("quick=3 (single hop), standard=3 (default; adds a gap-recovery hop...), thorough=6 (paid...)") and explains that the question parameter accepts broad, multi-part natural language, going well beyond the schema's basic descriptions.

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

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

The description states the tool conducts "Grounded multi-source research across Pipeworx's 1463 STRUCTURED data sources" and "Decomposes your question into focused facets, routes each to the right one of 5,578 tools IN PARALLEL." It clearly distinguishes from ask_pipeworx and positions deep_research as the broad, multi-part research tool, making its purpose unambiguous.

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

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

The description explicitly says "Best for broad/multi-part questions over structured data" and "For a single lookup use ask_pipeworx" and "For BREAKING... topics, prefer ask_pipeworx." It also specifies account tiers and when to use deep_research vs. ask_pipeworx, providing clear when-to/not-to-use guidance.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail about the return payload: 'returns the top-N most relevant tools with names, descriptions, and full input schemas… each result is ready to call directly, no second schema lookup needed.' This goes beyond the structured annotations and is consistent with them.

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

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

The three sentences are purposeful: the first states the action, the second enumerates relevant domains, and the third explains return format and usage timing. It is front-loaded with 'Find tools' and contains no filler. The domain list is somewhat long but each item is informative.

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

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

Despite having no output schema, the description explicitly covers what the caller receives: top-N tool names, descriptions, full input schemas, and curated examples. It also provides the strategic context to invoke this tool first in a large toolset. It could mention relevance ordering or default limit, but the schema already documents limit, making the description adequate.

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

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

All six parameters are documented in the input schema (100% coverage), so the description does not need to restate them. It adds no parameter-specific semantics beyond the general 'describing the data or task,' and the schema already provides aliases and examples. Baseline 3 is appropriate.

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

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

The description opens with 'Find tools by describing the data or task,' a specific verb+resource combination that clearly identifies this as a tool-discovery meta-command. It distinguishes from sibling research tools by emphasizing browsing/searching the available tool set rather than answering a single query. The enumerated domains (SEC filings, FDA drugs, economic data, etc.) further clarify scope.

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

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

It explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available.' It also gives a when-not cue with 'not just one answer,' but it does not name specific sibling tools as alternatives, so it falls just short of full marks.

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 this as read-only, non-destructive, and idempotent, but the description adds substantial behavioral detail: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), describes specific return fields (cik, recent_filings, fundamentals, patents, news, LEI), discloses that patents API is sunsetting and 'soft-fails until reactivated,' and notes the GDELT→GNews fallback. These details go well beyond the annotations.

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

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

The description is front-loaded with concrete example queries ('Tell me about X', 'research Acme'), then provides the core purpose, followed by structured detail about fan-out and return fields. Every sentence serves a function—examples, scope, exclusions, fallbacks—without redundancy. It is long but appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (cross-source fan-out) and lack of an output schema, the description is remarkably complete. It specifies input constraints (ticker/CIK, not names), the full set of outputs (cik, company_name, recent_filings with URIs, fundamentals fields, patents status, news fallback, LEI), and behavioral edge cases (patents soft-fail, GDELT→GNews fallback). No critical aspect is left unexplained.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantics by providing concrete examples ('AAPL', '0000320193'), reiterating that names are not supported, and explaining the relationship to resolve_entity. This reinforces and clarifies the schema's parameter descriptions, warranting a score above baseline.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It uses a specific verb ('profile'), identifies the resource (US public company), and explicitly distinguishes itself from sibling tools by preferring it over 'chaining single-pack SEC/XBRL/news lookups.' The example queries anchor the purpose effectively.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear alternative for unsupported inputs: 'names not supported (use resolve_entity first if you only have a name).' This directly addresses when not to use the tool and what to use instead.

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 a safe, read-only, idempotent operation (readOnlyHint=true, destructiveHint=false). The description adds useful context about return fields and sort options, but does not disclose any behavioral edge cases (e.g., rate limits, pagination defaults, content truncation). With annotations covering the safety profile, this is acceptable but not rich.

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

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

Two sentences, front-loaded with the primary purpose. The first sentence covers core functionality and the second lists return fields. No filler or redundancy.

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

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

For a tool with 11 parameters and no required fields, the description covers the primary search dimensions but misses pagination, source/exclusion filtering, and qInTitle. It is adequate for a basic search but leaves several functional gaps uncovered.

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

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

The schema has 0% description coverage, so the description must compensate. It explains key parameters (q, domains, from/to, language, sortBy) and even clarifies sortBy values, but omits page, pageSize, sources, excludeDomains, and qInTitle. This is partial compensation for a large parameter set.

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 searches the NewsAPI article archive via specific criteria (keyword, domains, date range, language), which is a specific verb+resource. It distinguishes the archive scope from siblings like top_headlines, but does not explicitly name any alternative tool, so it falls short of a 5.

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

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

The description implies usage for article archive searches by describing the query parameters, but it provides no explicit guidance on when to prefer this over siblings (e.g., top_headlines for breaking news, search_within for narrower searches). There are no usage exclusions or alternative tool references.

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 destructiveHint=true and idempotentHint=true. The description's 'Delete' merely restates this, adding minimal behavioral context beyond the structured data. The mention of clearing sensitive data is more of a usage rationale than a behavioral trait.

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, no fluff, and the purpose is front-loaded. Every word earns its place, covering purpose, usage context, and related tools efficiently.

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

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

For a simple one-parameter deletion tool with annotations covering safety, the description fully covers what, when, and how to trigger deletion. No output schema is provided, but none is necessary for a delete operation. Complete in context.

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

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

Schema coverage is 100% with the key parameter already described as 'Memory key to delete'. The description adds 'by key' but provides no additional semantics beyond the schema, meeting the baseline of 3.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb (delete) and resource (memory). This unambiguously distinguishes it from sibling tools like remember and recall.

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

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

The description gives explicit when-to-use conditions (stale context, task done, clearing sensitive data) and mentions pairing with remember and recall. It lacks explicit when-not-to-use guidance or direct alternatives, so it doesn't earn 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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds transparent behavioral detail: it fetches the page, extracts specific elements, and emits a single text blob. No contradictions or hidden side effects are implied.

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 compact and front-loaded: first sentence nails purpose, second explains mechanics/output, third lists practical uses. Every sentence earns its place with no redundancy or filler.

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

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

This is a simple 2-parameter tool with no output schema, and the description sufficiently covers the output format ('standard llms.txt markdown', 'single text blob') and typical use cases. It provides enough context for an agent to invoke it correctly without further elaboration.

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% for both parameters, so the description doesn't need to repeat parameter details. It does add context by mentioning max_links implicitly through 'key links' and the goal of clean indexing, but doesn't provide substantial extra 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 uses a specific verb ('Generate') with a concrete resource ('llms.txt file'), and explains the process (fetches page, extracts title/description/key links, emits markdown). It clearly distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on llms.txt generation rather than broader AI visibility 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 gives clear context with explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It doesn't explicitly name alternative tools, but the scenarios strongly imply when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds context by listing the exact return fields and noting the default excludes inactive subscriptions, which informs the agent about the tool's scoping and output shape.

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

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

The description is two sentences, front-loaded with the primary action, then return fields, then usage guidance. No wasted words; every sentence contributes value.

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

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

For a simple list tool with one optional parameter and no output schema, the description provides the essential details: scope, return fields, default behavior, and when to use it. The annotations cover safety, so nothing critical is missing.

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

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

The schema description for include_inactive is fully self-explanatory ('Include cancelled subscriptions in the response (default false)'), and the tool description does not add further meaning to it. Since schema coverage is 100%, this meets the baseline but does not exceed it.

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

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

The description opens with a specific verb-resource pairing: 'List the caller's active subscriptions.' It clearly distinguishes this from sibling tools like subscribe and unsubscribe by mentioning its use for reviewing what you're monitoring and finding ids to cancel.

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

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

The description explicitly tells when to use this tool ('before adding more' or 'to find an id to cancel'), which implies the alternatives (subscribe/unsubscribe) without explicitly naming them. This provides clear situational guidance.

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

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

Annotations are all false/absent, so the description carries full burden. It discloses the two-phase behavior (filing returns a claim_token; passing it back later returns status/fix information), rate limiting (5/identifier/day), cost implications (free, doesn't count against quota), and human review cadence (daily digests, roadmap impact). This goes well 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?

While lengthy (~180 words), the description is densely informative: purpose, use cases, exclusions, workflow, rate limits, and quota are each covered in one or two sentences. It's front-loaded with the core purpose and every sentence earns its place given the tool's complex two-phase usage.

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

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

For a tool with 4 parameters, no output schema, and no useful annotations, the description covers all behavioral aspects: what to report, scope boundaries, how to structure feedback, the claim_token lifecycle, rate limits, and the impact of reporting. Nothing essential is left to guesswork.

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

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

Schema already provides 100% coverage with detailed descriptions for each parameter. The description adds workflow context: how claim_token connects a prior filing to a later read, and content guidance ('Don't paste the end-user's prompt') that clarifies message expectations. This adds value beyond the schema's per-parameter semantics.

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

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

The first sentence states a clear verb ('Tell the Pipeworx team') and resource (the Pipeworx team), then expands with specific feedback categories (bug, feature, data_gap, praise). It explicitly distinguishes from sibling tools by scoping to 'tools served by this Pipeworx connection' and contrasts with other MCP servers, making its purpose unambiguous.

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

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

Explicitly states when to use: for wrong/stale data (bug), missing tools (feature/data_gap), or praise. Provides exclusion: not for tools from other MCP servers, pointing to filing with that server instead. Also explains the claim_token follow-up workflow, effectively telling the agent how to use this tool vs creating a new report.

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

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

The description adds significant behavioral context beyond the annotations: it discloses the data source (CF analytics-engine), privacy (no PII), output composition (pack, tool, count), and caching behavior (5min-1h depending on window). This is genuinely useful transparency for an agent deciding whether to rely on the data.

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

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

The description is well-structured and front-loaded with the core function. It packs a lot of value into a compact format: main purpose, three use cases, and behavioral notes, all in a few sentences with no redundancy.

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

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

Given the tool is simple (one optional parameter, no output schema) and annotations are strong, the description covers all necessary context: what it returns, when to use, how data is derived, and caching. It is complete for an agent to confidently invoke this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description briefly mentions the window options but does not add meaning beyond what the schema already provides (e.g., shorter windows = hot right now, longer = steady-state). No additional parameter semantics are needed.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It distinguishes itself from siblings like discover_tools by focusing on what other agents are actively calling, not simply listing available tools.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, aligning with agent needs) which gives clear context for when to use it. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of the 'explicit when/when-not/alternatives' benchmark.

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 far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing internal filters (PARTITION FILTER, SEMANTIC ANCHOR with 0.30 Jaccard threshold), the fill-check mechanism against CLOB depth, and the exact response structure. It warns about placeholder slugs and the condition 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade' – valuable behavioral context.

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

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

The description is long but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK) and uses bold labels. Every sentence carries specific technical value, and it is front-loaded with the primary purpose and invocation modes. No fluff or tautology.

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

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

With no output schema, the description fully explains the response format and edge cases, including the opportunities[] fields and partition_check object. It covers filtering logic, fill-check consequences, and fallback behavior (null arb signal). Given the tool's complexity, the description is exceptionally 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?

Although the schema already describes both parameters (coverage 100%), the description significantly enriches them by explaining what each mode does, how to format the slug or seed question, and the internal processing (e.g., walks child markets, flattens markets, runs comparator). It adds semantic depth that the schema descriptions lack, such as the recommended use case for each 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 opens with a precise verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection, not just edge monitoring or fill risk.

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

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

The description gives explicit usage guidance for each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)', with concrete examples. It also tells when not to use it and points to an alternative: 'For custom sizing use polymarket_fill_risk.' It even warns 'do not trade it' when the fill check fails, providing a clear decision boundary.

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 readOnly/idempotent annotations, the description discloses rich behavioral details: model families (lognormal barrier, GDELT ratio), per-sport alpha values, the rare-by-design nature of concentrated longshots, a 24h-move warning, caching behavior, and diagnostic counters that explain why segments are empty. This adds substantial context 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 and dense, but it is well-organized with clear section markers (e.g., 'FIVE MODEL FAMILIES', 'TRADEABLE-EDGE KNOBS', 'RESPONSE TOP-LEVEL'). Every sentence carries information; however, some algorithmic details (per-sport α values) could be moved to external docs without losing invocation guidance. It is structured but not particularly 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?

With no output schema, the description fully specifies the response structure: by_segment segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It describes per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, market.spread_pp, market.volume) and the 24h-move warning. For a tool with 9 optional knobs and complex segmentation, this is complete.

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

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

The schema already covers 100% of parameters, but the description adds cross-parameter meaning: it explains that min_kelly never filters partition arbs because parent-level kelly_fraction_half is 0 by design, and that min_partition_leg_kelly applies to per-leg Kelly inside top_legs. It also explains how tradeable-edge knobs interact with opportunity 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 opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and differentiates from siblings like polymarket_arbitrage (structural arbitrage) and polymarket_edge_tracker (edge tracking) by focusing on discovery and segmenting model families.

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

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

It clearly frames when to use the tool: 'agents discover opportunities without paging hundreds of markets.' It explains knobs like min_liquidity/max_spread_pp as tradeable-edge filters and notes Fed bets are excluded from ranking. However, it does not explicitly name alternatives or say 'use this instead of X,' so it lacks direct exclusionary guidance.

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

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

The description discloses significant behavioral details beyond the annotations: the 60-day snapshot TTL, that snapshots are written on cache-miss (so gaps mean no scan), that decay is based on daily closes of edge_pp_net not intraday, and that expired opportunities are closed/resolved/arbed away. It also explains the response structure in detail. Annotations already mark it as read-only and non-destructive, but the description adds rich operational context.

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

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

The description is long but densely packed. It is front-loaded with the core question, then systematically covers arguments, response structure, and limitations. Every sentence adds value—no fluff or redundancy. The structure (Args, RESPONSE, LIMITS) aids scannability.

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

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

Given there is no output schema, the description thoroughly explains the response fields (tracked[], expired[], snapshot_dates[]) with their meanings, including how to interpret them (e.g., median lifespan as competition clock). It also covers edge cases like snapshot gaps and TTL bounds. This is complete for an agent to decide when to call and how to interpret results.

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

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

Schema coverage is 100%, and the description does not add substantial meaning beyond the schema. It repeats default values and introduces 'snapshot family' but the schema already provides this detail. The description's 'max 30' is actually less precise than the schema's 'clamp 2-30'. There is no deep parameter behavior explanation, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry. It uses a specific verb-resource combo ('edge persistence and decay telemetry built from daily polymarket_edges snapshots') and directly answers the question 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges, which likely provides current edges rather than historical trend analysis.

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

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

The description provides clear context on when to use the tool: when you need to know edge persistence/decay, with a practical scenario (fresh vs. 3-week-old edge). It does not explicitly exclude alternatives, but the purpose and context make it obvious. The absence of explicit 'use X instead' prevents 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 signal readOnly/openWorld/idempotent, and the description adds behavioral details: walks the ladder, returns specific fields, interprets size_usd differently per mode, and discloses that partial basket fills create unhedged directional risk. No contradiction with annotations.

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

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

The description is long but well-structured with SINGLE-MARKET/BASKET/USE THIS sections, and every sentence carries essential information. It could be tightened, but the length is justified by the tool's complexity.

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

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

Despite no output schema, the description enumerates all key outputs for both modes, explains the risk of partial fills, and provides when-to-use guidance. Given the tool's complexity, this is comprehensive.

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 four parameters have schema descriptions, so baseline is 3. The description adds extra meaning by explaining side defaults per mode, size_usd as max spend vs target proceeds vs settlement notional, and the mutual exclusivity of market vs event (REQUIRES one). This pushes 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 opens with a specific verb phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth', clearly distinguishing it from sibling arb/edge tools. It names exact modes and outputs, making the tool's scope 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?

It explicitly instructs to use before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500, and explains when to use single-market vs basket mode. It also implicitly warns against relying on theoretical overround on thin books.

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 read-only and idempotent annotations, the description details the exact output structure: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning with two specific trigger conditions, temporal_alignment field, and skipped_cross_type/subtype counters. This goes far beyond the annotations, proactively explaining edge cases and how to interpret the response, with no contradiction.

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

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

The description is long (about 250 words) but well-structured with bolded section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with a clear first sentence. Every sentence carries relevant operational detail for a complex tool, though some passages could be tightened (e.g., the final warning). It is substantial but not wasteful.

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

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

Given no output schema, the description carries the full burden of explaining return values and edge cases, and it delivers. It explains the spread calculation, compatibility_warning triggers in two distinct scenarios, temporal_alignment's meaning, and skipped_cross_type/subtype counters. It even covers both usage modes and the override relationship, making it a remarkably complete description 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?

The schema covers all three parameters with examples and enum-like descriptions (100% coverage), so the baseline is 3. The description adds the 'TWO MODES' concept and explains that explicit kalshi_event_ticker and polymarket_event_slug 'override the topic-mapped side', which is a relational meaning not present in the schema. It doesn't detail error behavior or parameter validation, but this is solid supplemental 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 opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', clearly specifying the action (computing spread) and the two resources. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on compatibility warnings and bet-shape equivalence, not just raw price gaps, and by naming two concrete modes (topic vs explicit).

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 defines two usage modes ('topic' shortcuts vs explicit ticker/slug) and explains when each is appropriate. It also warns that 'pre-mapped ≠ tradeable' and that most preset topics currently return compatibility_warning, giving clear context for when results may be unreliable. However, it does not explicitly name alternative tools or state 'do not use this when...', so it stops short of 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=true and destructiveHint=false, and the description adds meaningful context beyond that: it explains scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the two distinct behaviors (retrieve by key vs. list all keys). This adds value 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 compact and well-structured: three sentences that front-load the primary action, then add contextual detail and tool relationships. Every sentence contributes value with no redundancy.

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

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

For a simple get/list tool with strong annotations and a 100% schema-coverage parameter, the description is largely complete. It covers both usage modes, scoping, and relationships to sibling tools. It does not explicitly handle error cases or return format, but the phrasing implies returns for both modes, which is adequate given the tool's simplicity.

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

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

Schema coverage is 100% since the only parameter `key` is fully described in the schema. The description reinforces the omit-to-list behavior but does not add substantial new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses specific verbs 'Retrieve' and 'list' to convey both modes of operation, clearly distinguishing itself from sibling tools remember and forget. It also provides concrete examples of stored context (ticker, address, research notes), making the tool's purpose unmistakable.

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

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

Explicitly states when to use the tool ('Use to look up context the agent stored earlier...') and names companion tools ('Pair with remember to save, forget to delete'), giving clear guidance on alternatives and the overall workflow.

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 states mark_read:true flags events as read and affects future calls, which mutates feed state. Annotations declare readOnlyHint:true and idempotentHint:true, directly contradicting this behavior. This is a clear annotation contradiction, so transparency scores 1.

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

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

Four sentences, each earning its place: purpose, return payload shape, filtering/mark_read behavior, and polling/alternative endpoint. No filler, front-loaded with the core action.

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

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

With schema covering parameter details and annotations covering safety intent, the description completes the picture with return payload fields, stateful mark_read behavior, and an external endpoint. It does not repeat limit or unread_only semantics, but those are already in the schema. Slight deduction for not mentioning the public availability of the alternate endpoint, though it is implied.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). The description adds value by providing a concrete type example ('sec_8k'), explaining the mark_read effect on subsequent calls, and clarifying the since parameter with ISO timestamp, which goes beyond bare schema definitions.

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

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

The description opens with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly states the scope (most recent alerts written to a persisted feed) and distinguishes from siblings like list_subscriptions and recent_changes by focusing on fired events with a persistent feed. The alternative endpoint mention further clarifies its role.

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

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

It gives clear context for when to use the tool (polling the subscription feed) and even points to a script/dashboard alternative (registry.pipeworx.io/alerts.json). However, it does not explicitly name sibling tools to exclude, so while context is strong, exclusions are implied rather than stated.

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

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

Building on the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds substantial behavioral detail: fan-out to SEC, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and rate-limit fallback logic. This far exceeds what annotations alone convey.

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

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

The description is dense but not bloated. It front-loads with natural-language triggers, then uses compact semicolon-separated clauses to convey source list, fallback logic, date format, return shape, and the alternative tool. Every sentence carries useful information, though a slightly shorter form would be possible.

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 lack of an output schema, the description explicitly states the return structure: structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. It also covers edge cases like GDELT rate-limiting and USPTO soft-fail, making the tool's behavior fully specified.

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

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

The input schema covers all three parameters with descriptions, so the baseline is 3. The description goes further by giving concrete formats for `since` (ISO or relative shorthand), examples for `value` (ticker or zero-padded CIK), and clarifying `type` only supports 'company'. This enriches but doesn't merely repeat 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 opens with multiple natural-language phrasings and clearly identifies the tool as a change feed for a company over a time window, executed in one parallel call. It also distinguishes itself from sibling entity_profile by explicitly contrasting time-windowed changes against static profiles.

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

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

The description gives an explicit alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also recommends typical `since` values ('30d' or '1m'). It doesn't address all possible sibling tools, but the primary ambiguity is resolved.

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

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

Beyond annotations (idempotentHint, non-destructive), the description adds key behavioral details: memory is scoped by identifier, and retention differs for authenticated users (persistent) vs anonymous (24 hours). This is crucial context for an agent deciding whether to rely on the stored data.

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 compact and well-structured: main action first, then usage trigger, storage semantics, retention policy, and sibling pairing. Every sentence serves a purpose 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?

For a simple two-parameter tool with no output schema, the description covers the core purpose, use cases, storage scope, persistence behavior, and integration with related tools. It is sufficiently complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples (ticker, address, preference) and explaining that entries are stored as a key-value pair scoped by identifier, enriching the purpose of both 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?

The description clearly states the tool's function with a specific verb ('Save data') and resource ('key-value pair'). It distinguishes from sibling tools recall and forget by explicitly naming them as counterparts for retrieval and deletion.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward...' with concrete examples. It also directs to paired tools (recall, forget) for related operations, effectively indicating when not to use this tool.

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

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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds significant behavioral context: it cascades through multiple lookup endpoints, degrades gracefully (if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return), and describes the output format (identifiers labeled with source, unresolved identifiers listed explicitly). 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 front-loaded with example queries, which is effective. While it is relatively long, every sentence adds value—explaining supported types, internal cascading, graceful degradation, and output format. It could be slightly more concise, but the structure is clear and logical.

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 that there is no output schema, the description thoroughly explains what the tool returns: identifiers labeled with source, unresolved identifiers listed explicitly, and specific identifiers for each type (CIK, ticker, LEI, FIGI for companies; RxCUI, ingredient, brand for drugs). It also covers edge cases like graceful degradation. This is sufficient for an agent to understand the tool's behavior and expected output.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the description adds meaning beyond the schema: for the 'company' type, it mentions that ISIN is also accepted (schema only lists ticker, CIK, or name) and explains the resolution process. This extra context helps the agent understand the full range of valid inputs.

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

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

The description opens with example queries that clearly illustrate the tool's purpose: resolving user-spoken names to canonical identifiers. It explicitly states 'Use FIRST whenever you have a name but need an ID.' and distinguishes between supported entity types (company, drug) with detailed explanations of what identifiers are returned, making the purpose unmistakable and differentiating it from sibling tools like entity_profile or compare_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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' and provides concrete query examples that signal when to invoke the tool. It does not name alternative tools or explicitly state when not to use it, but the context is clear enough that an agent can infer the tool's primary 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?

The description discloses that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. Annotations already declare readOnly, idempotent, and non-destructive; the description adds useful detail about the underlying mechanism and output structure, covering the key behavioral traits 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 three sentences, front-loaded with the main action, and includes only relevant details. It avoids fluff and redundancy, making it 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?

With no output schema, the description compensates by specifying the return fields (score, confidence, signal density). It also explains the use case and underlying probe. However, it doesn't mention potential limitations like required entity count or model-specific key requirements (though handled by schema). Overall, it is sufficiently complete for an agent to 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 description coverage is 100%, so the schema already explains all parameters. The description does not add additional semantics beyond what the schema provides (e.g., it doesn't elaborate on the 'entities' array structure beyond 'your brand + N competitors', which is already in the schema). Baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling ai_visibility_check by emphasizing multiple entities, and from generic compare_entities by specifying AI visibility focus. The purpose is unambiguous.

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

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

It provides a clear usage context: 'Useful for competitive AI-marketing audits' with an example question. It implies single-entity checks should use ai_visibility_check, though it doesn't explicitly state 'when not to use' or name the alternative. This is clear but lacks explicit 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?

Despite annotations already indicating read-only/idempotent safe behavior, the description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. This goes beyond annotations to set latency expectations and failure semantics. 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?

Every sentence earns its place: purpose, usage trigger, return format, ecosystem limitation, and failure behavior. It is dense but well-organized, with the main purpose front-loaded and no redundant phrases. Despite its length, it remains concise relative to the complexity of a composite tool.

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

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

Given no output schema and the complexity of a two-source composite, the description covers purpose, return fields, ecosystem scope, latency, and partial failure behavior. It fully equips an agent to understand what will happen, what to expect, and when to prefer other tools. Very complete.

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

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

Schema coverage is 100%—both 'package' and 'version' already have clear descriptions. The tool description adds little beyond what the schema provides, except indirectly referencing version history and alternatives, which are return fields rather than parameters. Baseline 3 is appropriate per rubric when schema fully covers params.

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's a composite check for 'should I add this npm package' that fans out to deps.dev and bundlephobia. Specific verb (scan/check), resource (npm dependency), and scope (license, advisories, bundle size) are all present, distinguishing it from generic research tools.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and provides an exclusion for non-NPM ecosystems, directing PyPI/Maven/Cargo/Go to deps.dev:version directly. This gives clear when-to-use and when-not-to-use guidance relative to alternatives.

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

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

Annotations already declare readOnly and idempotent, and the description adds valuable behavioral details beyond that: BGE-base-en embeddings, cosine similarity over 500-char windows, a 200K char cap, and truncation flagging. This is rich context that helps predict tool behavior.

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

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

Three sentences deliver clear purpose, usage guidance, and behavior without fluff. Information is front-loaded with the core function first, then use cases and technical details.

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 covers return values (passages, offsets, scores), limitations (cap, truncation), and integration with sibling tools. It is self-contained for an agent to invoke and interpret results 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 good parameter descriptions, so the baseline is 3. The description reinforces parameter usage (e.g., 'text you already pulled', 'top-N' for limit) but does not add significant new semantic meaning beyond schema examples.

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

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

The description clearly states the tool performs semantic search inside a provided text, with specific examples (SEC 10-K body, article) and distinct output (passages with offsets and scores). It differentiates from siblings by focusing on searching within already-fetched content, explicitly pairing with ask_pipeworx_grounded for grounding.

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

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

It provides explicit guidance on when to use: 'Use when the record is too big to cram into the prompt.' It also names the alternative ask_pipeworx_grounded and explains the workflow pairing, making the usage context very 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds domain-specific behavior: sources are filterable by category, language, and country, and returns specific fields (id, name, description, URL, category) 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?

Two sentences totaling 31 words, front-loaded with the action ('Return available NewsAPI publisher sources'). Every sentence earns its place, with no fluff or repetition of structured data.

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

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

The tool has three optional parameters, no enums, and an output schema. The description covers purpose, filters, and downstream use, which is largely complete. It omits default behavior when no filters are applied, but given the simplicity and annotation richness, the description is adequate.

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

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

Schema coverage is 0% (parameters are just type 'string' with no descriptions), so the description must compensate. It names all three parameters and clarifies they act as filters, but does not provide valid values or format hints beyond what the schema examples show. This is partial compensation, not full.

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

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

The description clearly states the tool returns available NewsAPI publisher sources, distinguishing it from siblings like top_headlines and everything by focusing on source metadata. The verb 'Return' and resource 'available NewsAPI publisher 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 explicitly advises using returned source ids to filter top_headlines or everything, providing a clear workflow and differentiating this tool from those siblings. It lacks explicit exclusionary language ('do not use for headlines'), but the context strongly implies the intended 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?

Discloses rich behavioral details beyond annotations: the always-on feed with retrieval methods, email/SMS delivery specifics, 10/day SMS cap, phone verification requirement, webhook HMAC signing, one-time secret, and auto-disable after 10 consecutive failures. This goes far beyond the annotation 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 dense yet well-structured: purpose, requirements, supported types, and delivery channels. Every sentence adds operational detail, and there is no redundancy or filler. It manages to pack a great deal of useful information into a compact form.

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 medium-complexity tool with no output schema, the description covers prerequisites, all relevant subscription types, delivery channel mechanics, and return values (subscription ID, webhook secret). It also gives retrieval endpoint for the feed, leaving the agent with sufficient context to invoke and interpret results.

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

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

The schema already has 100% parameter coverage with type-specific examples, so the baseline is 3. The description adds extra meaning through concrete semantic explanations (e.g., 'items:["5.02"] = officer change', 'topic:"fed"') and clarifies delivery channel behavior (feed is always on, retrieval endpoint, webhook failure handling), nudging this to a 4.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also states the return value ('Returns the new subscription id'), making the tool's purpose unmistakable. This clearly distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides concrete context on when to use the tool: for proactive monitoring, with supported types and delivery channels. It mentions requirements (OAuth account, phone verification) and limitations (anonymous/BYO cannot persist). However, it does not explicitly name alternatives or state when not to use, so it falls short of a perfect 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, so the safety profile is covered. The description adds valuable behavioral details: it returns category-bucketed example questions drawn from a live catalog, supports an optional topic parameter to focus results, and describes the return content (exact tool + argument shape). This goes beyond the annotations and gives the agent a clear picture of what to expect.

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

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

The description is relatively long but densely packed with useful information: example queries, category list, return behavior, and usage instructions. It is front-loaded with the key question phrases and clearly structured. While it could be trimmed slightly, every sentence contributes to understanding the tool's value and usage, so it earns a 4 rather than a 3.

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

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

Given there is no output schema, the description adequately explains return values (category-bucketed example questions with tool/argument shapes). It covers both the no-argument full spread and the topic-focused variant, and points to related meta-tools for further learning. The description is complete for an onboarding tool of this complexity.

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

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

The input schema already provides 100% coverage of the single optional parameter 'topic', including a list of valid values and the default behavior. The description reinforces this with examples ('finance', 'pharma', 'betting') and expands the category list with richer labels (e.g., 'company financials', 'drugs & clinical trials', 'prediction markets'), adding meaning beyond the schema. The baseline for high schema coverage is 3, but the additional context justifies a 4.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions to help an agent discover what to ask Pipeworx. It explicitly distinguishes itself from siblings by mentioning that each example includes the exact tool and argument shape, and it references meta-tools like ask_pipeworx and entity_profile. The verb 'suggest' is specific and the resource (question ideas) is unambiguous.

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

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

The description provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also covers the no-arguments vs. topic-scoped usage and lists the meta-tools to learn, giving clear context for when to use this tool over alternatives. The only minor gap is that it doesn't explicitly say when not to use it, but the 'first' directive is strong enough.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds return fields and filter options, but it does not disclose important behavioral constraints such as the mutual exclusivity of country/category with sources, or pagination behavior (page/pageSize). These are meaningful traits beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and succinctly lists filters and return fields. Every sentence contributes useful information without redundancy.

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

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

With an output schema present, the description's mention of return fields is a bonus. It covers the main filtering options and the tool's purpose, making it largely complete. However, it omits pagination parameters and the restriction on combining sources with country/category, which would be needed for fully reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'country' (ISO 2-letter), 'category' (with enumerated values), 'sources', and 'q', but omits 'page' and 'pageSize' entirely. The description adds value for 4 of 6 parameters but is not complete, leaving pagination semantics undocumented.

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 fetches 'current top news headlines' from NewsAPI, with a specific verb ('Fetch') and resource ('top news headlines'). It lists the filtering dimensions (country, category, sources, q), which distinguishes it from generic search tools like 'everything' that search all articles.

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

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

The description implies usage for top headlines but does not explicitly state when to use this tool versus the 'everything' sibling (which likely searches all articles). No exclusions or alternative guidance is provided, making the usage context clear but not explicitly differentiated.

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 detail beyond annotations: ownership enforcement (only cancel own subscriptions) and soft-delete semantics (deactivated, not deleted, preserving historical events via recent_alerts). These are not present in the annotations and enrich the agent's understanding.

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, front-loaded with the primary action. Every sentence provides useful information with no filler, making it easy to scan.

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

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

For a simple one-parameter tool, the description covers the main behavioral aspects: cancellation, ownership, side effects, and relationship to recent_alerts. While it omits error handling or return values, the annotations and simplicity make this sufficient.

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

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

Schema coverage is 100% (the single id parameter is well-described in the schema). The description merely repeats 'by id' without adding new meaning, so it does not enhance parameter 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 cancels a subscription by id, using a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions, and adds context about ownership enforcement and deactivation.

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 tool's purpose implies when to use it (canceling a subscription), but it does not explicitly compare with alternatives or state when not to use it. The ownership and historical event context provide some guidance, but no direct exclusions or alternative references are given.

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 provides substantial behavioral context beyond the annotations: two distinct processing paths (SEC EDGAR/XBRL vs. grounded pipeline), the verdict taxonomy, and a crucial caller warning that 'could_not_verify' indicates the check did not happen (with verification_error) and must not be treated as evidence. This disclosure is essential for correct use and goes far beyond the readOnlyHint/idempotentHint 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: it front-loads common user phrasings, states the core purpose, then explains routing, return values, and important caveats. Each sentence adds distinct value, with no redundant fluff. The length is justified by the tool's complexity.

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

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

Even without an output schema, the description enumerates the verdict types, return contents (actual value, citation, reasoning), and the error field for could_not_verify. It explains unsupported, covers both processing routes, and gives usage context. This is highly complete for an agent to invoke and interpret the tool correctly.

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

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

The input schema already provides complete descriptions for both parameters (100% coverage), including tolerance_pct's meaning and default. The tool description adds no extra parameter-level semantics beyond referencing 'exact percent-delta math' for the SEC path, so the baseline 3 applies.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources. It uses specific action verbs ('fact check', 'verify the claim', 'confirm or refute') and differentiates itself from siblings by describing its function as a single consolidated step replacing 4–6 sequential calls.

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

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

The description explicitly tells the agent when to use it ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the internal routing for company-financial vs. other claims. It mentions it 'Replaces 4–6 sequential calls' which implies an alternative, but it does not name specific sibling tools or provide explicit when-not-to-use conditions, so it's not a perfect 5.

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