spacenews

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

Annotations already cover readOnly/openWorld/idempotent/destructive hints. The description adds meaningful behavioral context beyond those: cost implications ('you pay Anthropic directly'), the default model fallback, and the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). 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?

Three sentences, no filler. The core purpose is front-loaded, followed by key configuration notes and use cases. Every sentence earns its place: one for what it does, one for how to configure, one for output and applicability.

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

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

Given 4 parameters, no output schema, and rich annotations, the description covers the essential contract: it describes the output shape, default model, optional Anthropic usage with cost, and real-world scenarios. It is sufficient for an agent to decide whether and how to invoke the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the relationship between `models` and `_apiKey` (e.g., key only needed if Anthropic is in models), default behavior when `models` is omitted, and that the key is passed through to api.anthropic.com. This enriches the schema's static parameter descriptions.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb+resource+outcome, and it distinguishes itself from siblings by focusing on LLM knowledge scoring and per-model visibility metrics.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies when to pass the `_apiKey` (to also probe Anthropic) and that the default model is free. However, it does not name specific alternatives or state when not to use this tool, so it stops short of full 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond these hints: routing across 5,529 tools, automatic argument filling, stable pipeworx:// citation URIs, and that it works on every tier with one fast call. 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 longer than average but every sentence earns its place: it covers preference, mechanism, usage triggers, examples, and escalation paths. It is well-structured with the key directive ('PREFER OVER WEB SEARCH') front-loaded. Slightly verbose but justified for a multi-purpose 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?

For a tool with one essential parameter and no output schema, the description explains what happens internally (routing to 5,529 tools), what the user receives (structured answers with stable citations), and operational details (works on every tier, one fast call). It also addresses edge cases like breaking news and multi-part questions, making it fully complete for agent 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?

The input schema provides 100% coverage, with 'question' described as 'Your question or request in natural language' and aliases (query, q, prompt, text, input) each clearly labeled as aliases. The description adds example queries but does not materially extend the schema's parameter semantics, so the 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: it routes factual questions to 5,529 tools across 1,455 sources and returns structured answers with stable citation URIs. It specifies the exact verb ('ask') and resource ('pipeworx'), and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives (ask_pipeworx_grounded, deep_research). It also lists trigger phrases and concrete examples, covering both when-to-use and when-not-to-use scenarios.

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

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

The description adds valuable behavioral context beyond the annotations: it is a full working router, not a fallback, and its behavior is subject to live candidates being tested. It also discloses the historical retirement date and that results are compared to the stable router. This exceeds the safety hints already provided.

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

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

The description is somewhat long but each sentence carries unique information: relationship to ask_pipeworx, current experimental status, usage guidance, and reassurance that it's fully functional. It is front-loaded with the core purpose, and only slightly exceeds ideal brevity.

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 stating the response shape is identical to ask_pipeworx. It also covers the tool's experimental nature, its current inert state, and how it is evaluated, providing a complete picture 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?

The input schema already documents all parameters with 100% coverage, so the description needn't repeat them. It references 'same arguments' as ask_pipeworx, but adds no extra semantic nuance beyond the schema, meeting the baseline for high schema coverage.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same tool set and arguments. It explicitly distinguishes itself from the stable sibling (ask_pipeworx) by its experimental routing improvements, 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?

It states when to use it ('when you want the newest routing') and references the stable router as the comparison point. It also notes that with no active candidate it currently matches ask_pipeworx exactly, providing practical context, though it does not explicitly state when not to use it.

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

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

Despite strong annotations (readOnlyHint, idempotentHint, etc.), the description adds substantial behavioral detail: it ensures answers use ONLY the tool result, describes success/refusal return shapes, enumerates specific refusal_reason values, and mentions the extra LLM call cost. 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 dense but every sentence earns its place: purpose, mechanism, return format, refusal reasons, use cases, cost tradeoff. It is front-loaded with the core distinction from ask_pipeworx and uses clear structured formatting for refusal reasons. No fluff.

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

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

Even without an output schema, the description fully covers return values ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and all failure states. It also addresses cost, routing, and use cases. Highly complete for a complex tool.

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

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

Schema coverage is 100% and all parameters are aliases for 'question' with descriptions. The description adds no new parameter-specific semantics beyond restating that it takes a natural-language question. Per the baseline, 3 is appropriate because the schema fully handles 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 clearly states a specific purpose: a hallucination-resistant answer mode that extracts answers grounded in tool results. It explicitly contrasts with ask_pipeworx, distinguishing itself as the grounded variant. The verb 'extracts' and the resource (tool result) are clearly identified.

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: use when answers will be quoted/cited/acted on and facts must not be invented. It also names the alternative (ask_pipeworx) for casual lookups and justifies the tradeoff (extra LLM call). This is a model of when-to-use/when-not-to guidance.

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

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

While annotations already declare readOnly, openWorld, and idempotent, the description goes far beyond them by disclosing resolver contracts, safety short-circuits (status:'low_confidence_match'), market-closed behavior, wide-spread tradeability warnings, parent-event extraction, and resolution-rule risk. It even explains the blocking nature of closed-market handling. This is exemplary behavioral disclosure.

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

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

The description is extremely verbose, running many long paragraphs with embedded headers and extensive edge-case explanations. While it is front-loaded with a clear opening sentence and contains genuinely valuable information, every sentence does not earn its place—there is substantial redundancy (e.g., both the market-closed and low-confidence paths are described twice in different words). This length makes it hard for an agent to quickly parse.

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?

Since there is no output schema, the description fully carries the burden of explaining return values. It covers response shapes (result.market, result.analysis, result.evidence), resolver confidence contracts, parent_event structures, news fallback fields, and blocking statuses. It even quantifies warning thresholds (e.g., >10pp spread, 24h move vs. model edge). This is as complete as one could reasonably want for a complex research tool.

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

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

The schema already covers 100% of the parameters with detailed descriptions including defaults. The tool description adds lots of behavioral context but not much new about the parameters themselves; the market slug/URL/question-text flexibility is already in the schema. The fan-out examples illustrate behavior but don't clarify parameter syntax or constraints beyond what the schema provides.

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

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

The description states a clear, specific verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It immediately differentiates from sibling research tools by naming exact use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives a concrete sense of what the tool returns (evidence packet plus market-vs-model comparison).

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

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

The description provides explicit use cases ('Use for...') and even gives a conditional directive ('Check this before sizing sports/esports/event-occurrence bets'). However, it does not name alternative tools or state when NOT to use this tool in favor of a sibling, so it lacks a full when/when-not/alternatives structure.

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; the description adds sourcing (SEC EDGAR/XBRL, FAERS/FDA), fiscal-year handling, sorting by primary metric, and per-entity citation URIs. No contradiction is present.

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 packs many facts into a compact block. Each sentence contributes a distinct piece: triggers, preference rule, type-specific behavior, sorting, and return format.

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 two-parameter tool with no output schema, the description covers inputs, data sources, sorting, output shape (paired data + citation URIs), and efficiency gain over sequential lookups. No critical behavioral gap remains.

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, but the description adds meaning: type='company' maps to financial metrics, type='drug' to FAERS/FDA/trial counts, and values are illustrated with ticker/CIK and drug-name examples. This goes beyond the schema's simple enum.

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 concrete trigger phrases and states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It explicitly differentiates from sequential single-pack lookups, making the purpose unmistakable.

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

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

The 'ALWAYS PREFER over sequential single-pack lookups' sentence provides an explicit alternative and when-to-use rule. It also enumerates trigger examples ('which is bigger', 'rank these companies') and clarifies domain types.

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 behavior far beyond annotations: account/paid tier requirements, NOT open-web search, gaps[] never invented, semantic excerpting, latency 15-60s, citation fetchability, contradictions[] for standard/thorough. No contradiction with readOnlyHint/idempotentHint.

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

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

The description is long but dense with unique operational details. It's appropriately structured for a complex research tool—each clause adds nuance (depth effects, citation URIs, excerpting)—yet could be trimmed: multiple references to ask_pipeworx appear. Slightly over-stuffed.

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 no output schema, the description fully specifies the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[] (for standard/thorough). Account and latency details close the remaining gaps. Nothing important seems 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?

Schema already covers 100% of params and the depth enum is well-described. The description adds context on what each depth level actually does (quick=3 facets single hop, standard default adds gap recovery + contradictions, thorough paid adds iterative lead chasing), which is valuable for agent choice.

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 grounded multi-source research across 1455 structured data sources in one call, and explicitly contrasts it with ask_pipeworx for single lookups. The verb 'research' and resource 'structured data sources' are specific, and the note 'this is NOT open-web search' distinguishes it from sibling search 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?

It gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and says for single lookups or breaking news to prefer ask_pipeworx. It also specifies account prerequisites and paid depth levels. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This clarifies the output structure and direct usability, going 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 three sentences, front-loaded with the core purpose, and each sentence earns its place: purpose + domain list, return format benefit, and usage timing. No redundant or filler content.

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

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

With no output schema, the description takes responsibility for explaining return values, and it does: results include names, descriptions, and full schemas with curated examples, ready to call directly. It also provides usage context ('Call this FIRST'). This is complete for a discovery tool with rich annotations.

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

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

Schema coverage is 100%, with descriptions for query, limit, and all aliases. The description reinforces that query is a natural language task description, but it does not add significant new semantic meaning beyond the schema. The baseline of 3 applies since the schema already fully documents 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: 'Find tools by describing the data or task.' It uses a specific verb (find) and resource (tools), and the domain list (SEC filings, FDA drugs, etc.) differentiates it from sibling tools like search_articles or 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?

The description explicitly tells when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It gives a clear when-to-use scenario, though it does not name specific alternative tools or explicit when-not-to-use conditions beyond the 'not just one answer' hint.

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 richly discloses behavior beyond annotations: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific fields with counts and sorting; notes patents API sunset May 2025 soft-fail; and describes GDELT→GNews fallback. This is highly transparent and consistent with the readOnly/openWorld/idempotent 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 each sentence earns its place: examples, preference guidance, source list, return fields, failure caveats, and input restrictions. It is front-loaded with examples, though it runs on as a single paragraph and could benefit from bullet-style structure for readability.

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

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

With no output schema, the description fully compensates by enumerating exact return components (cik, company_name, recent_filings with URIs, fundamentals with specific metrics, patents, news, LEI), including failure modes and fallbacks. It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds practical examples ('AAPL', '0000320193'), clarifies zero-padded CIK, and reinforces that names are not supported and resolve_entity should be used first, going slightly beyond the schema.

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

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

The description clearly states it produces a 'full cross-source profile of a US public company in ONE parallel call,' with specific examples and a defined resource. It distinguishes itself from siblings by explicitly contrasting with chaining single-pack SEC/XBRL/news lookups and referencing resolve_entity for name-based 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?

Usage is explicitly tied to user intents like 'Tell me about X' and 'research Acme,' with an explicit 'ALWAYS PREFER' instruction over chaining single-source lookups. It also provides a clear exclusion: names are not supported, and advise to use resolve_entity first.

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 adds context about clearing sensitive data and memories stored by the agent, but does not go beyond these annotations with new behavioral details like irreversibility or permission requirements.

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 concise sentences, front-loaded with the core action. Each sentence earns its place: action, usage scenarios, and tool relationships. No redundant wording.

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, no-output-schema tool with rich annotations, the description fully covers what, when, and relationship to siblings. No gaps in understanding how to invoke or what to expect.

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

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

Schema description coverage is 100% with 'Memory key to delete.' The description only repeats 'by key' without adding extra meaning about the key's format, uniqueness, or behavior. 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 starts with a specific verb+resource: 'Delete a previously stored memory by key.' It clearly distinguishes from siblings like remember and recall by directly stating the deletion action.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with remember and recall, giving clear context for 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?

Annotations already mark it read-only, open-world, and idempotent. The description adds that it fetches an external URL, extracts content, and returns a single text blob, which is useful beyond the annotations. It does not disclose potential edge cases like network failures or JS-rendered pages, but the core behavior is transparent.

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

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

The description is concise yet well structured: it states the purpose, explains the process, notes the output format/location, and lists use cases—all in a compact, scannable form. 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?

The tool is moderately simple with 2 params, full schema coverage, and enriching annotations. The description sufficiently explains what it does and returns, but omits potential limitations (e.g., sites that block crawlers or heavy JS rendering), leaving minor gaps for complete confidence.

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 descriptive parameter details (URL example, max_links default and max). The description does not add semantic meaning beyond the schema, so the 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 opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It details the process (fetches page, extracts title/description/key links) and output format, clearly distinguishing it from siblings like scan_competitor_ai_presence or ai_visibility_check.

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

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

The 'Useful for:' list gives clear contexts (client indexing, own project, competitor audit) but does not explicitly mention when not to use it or name alternatives. This provides sufficient guidance for most agents, though it stops short of 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?

Annotations already declare the read-only, idempotent, non-destructive nature. The description adds useful behavioral context: sorting order (publication date) and the specific fields returned (title, summary, URL, image, source), which goes beyond schema details.

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

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

The description is concise, front-loaded with the action, and uses only two sentences that convey the purpose and return value without redundancy.

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

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

Given the simplicity (one optional parameter, clear output schema, and strong annotations), the description is complete enough. It conveys the core behavior and return details, with no missing critical information for a basic fetch operation.

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 single 'limit' parameter is fully described. The description does not add additional detail about parameters, 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 fetches the latest spaceflight news articles with a specific sorting (by publication date). This distinguishes it from siblings like search_articles or get_blogs.

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 use when you want the latest articles but does not explicitly mention alternatives or when-not-to-use scenarios. No guidance is given for choosing between this and search-related siblings.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds useful behavioral context: sorting by publication date and the exact return fields (title, summary, URL, image, source). 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 two concise sentences, front-loaded with the action and resource, and every word adds value. It avoids redundancy and is appropriately sized for the tool's simplicity.

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

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

Given the tool's simplicity (one optional parameter, strong annotations, and an output schema), the description is complete. It covers all essential aspects: what is fetched, sorting, and return fields, without missing critical information.

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 fully describes the single optional 'limit' parameter with default and max values. The description does not add additional parameter-level semantics, relying on the schema's 100% coverage, 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 specific action ('Fetch') and resource ('latest spaceflight blog posts'), and distinguishes it from siblings like get_articles by specifying the 'spaceflight' domain. It also mentions the sorting criterion, making the purpose unambiguous.

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

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

The description implies when to use this tool: when the latest spaceflight blog posts are needed. It provides clear context but does not explicitly mention alternatives or exclusions, such as when to use search_articles instead for more specific queries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral details: it returns active subscriptions by default, lists the response fields, and is scoped to the caller. 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?

Two sentences: first states purpose and return fields, second gives usage guidance. Every word earns its place, with no fluff or repetition.

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

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

For a simple read-only list tool with one optional parameter and rich annotations, the description is fully sufficient. It also lists return fields, compensating 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% for the only parameter (include_inactive) and the schema description fully explains it. The description does not add extra meaning about parameters, so the 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 clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists the exact fields returned, distinguishing it from sibling tools like subscribe/unsubscribe which perform mutations.

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 usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies it should be used before subscribe/unsubscribe, though it doesn't name those alternatives explicitly.

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 and provide no hints, but the description discloses key behaviors: returns a claim_token without an account, rate-limited to 5 per identifier per day, free, doesn't count against quota, and the team reads digests daily. 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?

Every sentence earns its place: purpose, usage scenarios, exclusion, token mechanics, rate limit, and quota. The description is front-loaded with the core purpose and then follows a logical flow with zero 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?

There is no output schema, but the description adequately explains the key return behavior (claim_token) and operational constraints. The only minor gap is it doesn't explicitly describe the return value for account-holders, but the overall guidance is sufficient for correct tool invocation.

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

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

Schema coverage is 100% with detailed per-parameter descriptions. The description adds meaningful extra semantics, especially for claim_token ('Filing without an account returns a claim_token; pass it back later...') and for message framing ('don't paste the end-user's prompt'). This exceeds the baseline 3 for full schema coverage.

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

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

The opening sentence clearly states the verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes this from sibling tools like ask_pipeworx or discover_tools by framing it as feedback/issue reporting for Pipeworx tools specifically.

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 enumerates when to use (bug, feature/data_gap, praise) and when NOT to use (tools from a different MCP server, with clear instructions to file elsewhere). It also clarifies uncertainty by pointing to the tool names listed by this connection.

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 behavior. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, just (pack, tool, count), and caching behavior (5min-1h depending on window). This enriches the annotation without contradicting it.

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. The bullet list adds value but is slightly longer than strictly necessary. Every sentence earns its place, but it could be tightened without losing meaning.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains the return shape (top tools, top packs, call volume), data source, privacy, caching, and use cases. No important context 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?

Schema coverage is 100%, and the schema already provides meaningful parameter description (window enum with interpretation). The tool description simply repeats the window values without adding new semantics beyond the schema, so the 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 clearly states what the tool does: it returns trending tool usage from other AI agents, including top tools, packs, and call volume over a recent window. The verb 'Returns' and specific resource make the purpose unambiguous, distinguishing it from sibling tools like discover_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 lists three concrete use cases for when to use this tool, such as discovering hot data sources and confirming canonical tool choices. It does not mention when not to use it or alternative tool names, 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?

Despite readOnlyHint and idempotentHint, the description adds substantial behavioral detail: partition_check threshold of >3pp, Jaccard similarity ≥0.30 for semantic anchoring, placeholder slug filtering (>20% returns null), and fill-check behavior with realizable_edge_pp ≤ 0 warning not to trade. It also explains skipped_low_similarity count and response 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 dense and long, but each section (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) adds unique operational detail. It is front-loaded with mode selection and ends with alternatives, but uses ALL-CAPS labels and includes internal function references (arbitrage.fill_check) that add length; still, it earns its place for a complex 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?

For a tool with two optional parameters, no output schema, and complex multi-mode behavior, the description thoroughly covers response fields, edge cases, and anti-trading warnings. It even explains the difference between theoretical and realizable edge, making it self-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?

Input schema covers both params with brief descriptions, but the tool description enriches them with concrete examples (event slugs like 'fed-decision-may-2026', topic seeds), notes that full URLs are accepted for event, and clarifies that no args triggers trending_scan. This goes well beyond the schema.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by naming the detection methods and explaining three invocation modes (no args, event, topic).

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 tells when to call with no args (trending_scan), when to use event mode (specific market), and when to use topic mode (cross-event themed scan), even recommending event for a specific market. It also directs users to sibling tool polymarket_fill_risk for custom sizing, providing an explicit alternative.

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 extensively discloses behavioral traits beyond the readOnly/idempotent annotations: it details the three response segments, the five model families within them, the edge metrics (edge_pp_net, kelly_fraction, etc.), the 24h-move warning, and the caching policy. It also explains that Fed bets are excluded from ranking due to data limitations, and that diagnostic counters are included to explain empty segments. This far exceeds the annotation baseline.

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 verbose but front-loaded with a clear purpose sentence. It packs a great deal of technical detail (model family thresholds, sports-specific alpha values, funnel counters) into a dense wall of text. While well-structured with segmented clauses, it is longer than necessary and would benefit from a brief usage summary or bullet points. It's informative but not 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?

There is no output schema, so the description must explain the return structure. It does so thoroughly, listing the top-level fields (by_segment, fed_candidates/fed_note, _diagnostics) and the per-opportunity fields. It also covers edge cases (e.g., empty segments via diagnostics, Fed bets excluded). Given the tool's complexity, the description is 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 covers 100% of the 9 parameters with descriptions, so the baseline is 3. The tool description adds significant value by explaining how min_kelly interacts with partition_arbs (never filters them, applies per-leg instead) and clarifying the role of min_liquidity/max_spread_pp as 'tradeable-edge filters.' This context is not present in the schema and is crucial for correct usage.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and differentiates itself by focusing on opportunity discovery for 'what should I bet on today' without paging hundreds of markets, and by describing three response segments (model_driven, structural_arbitrage, concentrated_longshot) that distinguish it from sibling 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 a clear use case ('what should I bet on today') and explains when to use it for discovering opportunities without exhaustive market paging. It also explains how the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) can be used to filter results. However, it does not explicitly mention when not to use this tool or point to alternatives (e.g., polymarket_arbitrage for pure cross-market arbitrage), so it's clear but lacks 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 mark the tool readOnly/openWorld/idempotent, and the description goes far beyond by detailing exact data sources, time-series semantics, computed fields (trend, decay_pp_per_day), handling of expired opportunities, and the meaning of snapshot gaps. It also discloses limitations (60-day TTL, daily closes not intraday) that are not present in 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 longer than average but densely packed with high-value information, front-loaded with the core question it answers, then structured into Args, RESPONSE, and LIMITS. Every sentence contributes meaningful detail, though the sheer length keeps it from being maximally 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 enumerates the response shape (tracked[], expired[], snapshot_dates[]) and explains each field's meaning, including derived metrics and edge cases (gaps, TTL, expiry). It also covers data provenance and limitations, making it 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% for both parameters, so baseline is 3. The description adds meaning by explaining 'days' as lookback with bounds and 'window' as a 'snapshot family' influencing which data source to read, which clarifies the conceptual role of each parameter beyond the raw schema.

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

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

The description clearly defines the tool as 'edge persistence and decay telemetry built from daily polymarket_edges snapshots,' with a specific verb implied ('answers how long has this edge existed and is it shrinking?'). It distinguishes itself from the sibling tool polymarket_edges by focusing on longitudinal edge decay and time-series tracking rather than current edge values.

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 this tool is relevant ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying use for evaluating edge longevity and decay. It does not explicitly name alternative tools or state when NOT to use it, but the context is strong and the LIMITS section adds practical usage boundaries (e.g., snapshot TTL, cache-miss gaps).

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 the tool as read-only and non-destructive. The description adds valuable behavioral context: it explains the meaning of 'verdict' (clean|degraded|cannot_fill), the risk of partial basket fills converting arb into directional exposure, and the semantic difference of size_usd between single-market and basket modes. 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 very long but every sentence packs essential information for a complex tool. It is front-loaded with a clear summary, then explains modes and outputs. The single dense paragraph is less readable than structured sections, but no sentence is wasted.

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

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

Given the tool's complexity (two distinct modes, no output schema), the description is remarkably complete. It enumerates the return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum vs realizable_sum, capture_ratio, thin_legs, forced_directional_risk, etc.) and provides usage context tied to real losses in arb-bot P&L. The absense of an output schema is compensated.

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?

While the schema covers all parameters at 100%, the description adds significant semantic layers: it clarifies that 'market' and 'event' are mutually exclusive modes, explains side defaults and behavior in each mode, defines size_usd as 'max spend on buys, target proceeds on sells' for single-market and as settlement notional for basket mode, and notes the clamp range of 10–1,000,000. This goes far 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+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by positioning this tool as a pre-trade risk check, not an edge finder or arb detector.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical edge not capturable on thin books, partial fills create unhedged directional risk), which gives clear when-to-use and alternatives.

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

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

Annotations already signal read-only, open-world, idempotent, and non-destructive. The description goes far beyond that by detailing safety fields: compatibility_warning has specific conditions (matched_pairs:0 with skipped_cross_type>0 vs matched_pairs:0 with skipped_cross_type:0), temporal_alignment explains when spreads are 'mathematically meaningless,' and skipped_cross_type/subtype counters expose dropped comparisons. 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 and dense, but each section earns its place: mode definitions, response structure, safety warnings, and caveats. It is front-loaded with the core purpose and organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It could be trimmed slightly, but the verbosity 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?

Given no output schema and a complex, multi-venue tool, the description covers output semantics (leg-by-leg prices, spread[].top_spreads_pp), edge cases (compatibility_warning conditions), temporal alignment, and skip counters. This is sufficient for an agent to invoke the tool 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?

Although schema description coverage is 100% and all three parameters are described, the description adds meaningful semantics beyond names and examples. It explains the relationship between parameters: explicit overrides ('Overrides the topic-mapped Kalshi side'), and clarifies the purpose of the topic parameter with a concrete list of shortcuts. This elevates it slightly above the baseline but is not a 5 since the schema already carries most of the 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 specific verb+resource+scope: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison and lists two explicit modes (topic vs explicit pairings), making the tool's function 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?

It explicitly defines when to use which mode: 'TWO MODES: (1) `topic` — 10 pre-mapped macro shortcuts ... (2) explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings.' It also warns about real-world applicability: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' This gives clear when-to-use and when-to-not-trust guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar for adding behavioral disclosures is lower. The description adds non-obvious context about scope visibility (anonymous IP, BYO key hash, account ID) and the conditional behavior of omitting the key to list all saved keys. This goes beyond what annotations provide, though it doesn't mention error cases or return format.

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

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

The description is two sentences. The first sentence states the core functionality and listing option; the second frame the use case and relationship to siblings. Every sentence carries weight with no fluff, and it's front-loaded with the verb and resource.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers what the tool does, how to invoke both modes, scope, and its place in the tool family. No significant gaps remain.

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

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

The schema already covers the 'key' parameter thoroughly (100% coverage), so baseline is 3. The description adds extra meaning by giving concrete examples of what keys represent (target ticker, address, research notes) and explicitly states the omit-to-list behavior, which reinforces the schema's description and helps the agent understand what values are expected.

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 ('Retrieve') and clearly distinguishes the tool from siblings by explaining both retrieval of a specific saved value and listing all keys. It also clarifies scope ('Scoped to your identifier'), which sharpens the purpose.

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 ('Use to look up context the agent stored earlier') and gives concrete examples of what to look up. It also names sibling tools and their roles ('Pair with remember to save, forget to delete'), providing clear guidance on alternatives.

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

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

The description states that setting mark_read:true will 'flag returned events read so the next call only shows newer ones,' indicating a state mutation. The annotations declare readOnlyHint=true, which implies no state change. This is a direct contradiction, and the description fails to reconcile this side effect with the read-only annotation.

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

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

The description is concise and well-structured: it opens with the core purpose, then covers the returned data fields, filtering options, the mark_read behavior, and a useful alternative access method. Every sentence contributes unique 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 no output schema, the description explains key returned fields and the effect of mark_read. It omits the full response shape and how unread_only interacts, but the tool's simplicity and the schema's parameter descriptions make this acceptable. The polling guidance adds practical completeness.

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

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

All 5 parameters are fully described in the schema, giving a solid baseline. The description adds meaningful context by providing a concrete type example ('sec_8k'), clarifying the ISO timestamp format for since, and explaining the functional effect of mark_read beyond the schema's property description.

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

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

The description begins with 'Pull fired events from your subscription feed,' making the primary verb and resource explicit. It further clarifies the content of the alerts (source, citation_uri, raw event payload), which distinguishes it from sibling tools like list_subscriptions and recent_changes.

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 concrete usage context: it mentions filtering by type and since, supports polling ('Polls work fine'), and offers an alternative external endpoint for scripts/dashboards. It does not explicitly compare against sibling tools, but the guidance is clear enough for most scenarios.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses the fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to PatentsView sunset, and the parallel execution model. This is significant behavioral context not inferable from 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 provides unique value: natural language triggers, source fan-out, parameter formats, return structure, and an explicit alternative. No filler; front-loaded with user intents.

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

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

For a complex tool with no output schema, the description covers the return shape (changes[], total_changes, citation URIs), the various data source behaviors, and temporal parameter handling, making it sufficiently complete for an agent to invoke correctly.

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

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

Schema covers all parameters with descriptions, and the description adds valuable examples (ISO date '2026-04-01' vs relative '7d', ticker 'AAPL' vs zero-padded CIK) and clarifies the `since` semantics. It goes beyond the schema's baseline by illustrating accepted values.

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 defines the tool as a change feed for a company over a time window, with natural language intents and explicit data sources (SEC, GDELT/GNews, USPTO). It distinguishes itself from the sibling tool entity_profile by specifying when to use the alternative.

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

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

Provides explicit usage context: 'What's new with X' / 'latest on Y' etc., and states when to use entity_profile instead. Also gives guidance on the `since` parameter format and fallback behavior, enabling the agent to choose correctly.

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 write/idempotent/non-destructive. Description adds persistence scope (authenticated vs anonymous 24h), key-value structure, and namespace by identifier, which go beyond annotations.

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

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

Three sentences, front-loaded purpose, no filler; examples are inline and valuable.

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?

Simple 2-param tool with good annotations and description covering purpose, usage, persistence, and tool relationships. No output schema, but not required to explain returns for this save operation; overall 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 covers both parameters with examples (100%). Description only restates key-value concept and doesn't add semantics beyond the schema, so baseline 3.

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

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

Clear verb+resource: 'Save data the agent will need to reuse later' with explicit pairing to recall/forget, distinguishing it from sibling memory 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?

Explicit when-to-use: 'Use when you discover something worth carrying forward...' with concrete examples, and alternative tools named (recall, forget).

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 well beyond the annotations (readOnly, idempotent). It details degradation behavior ('LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), explains that unresolved identifiers are explicitly stated under `unresolved` rather than omitted, and notes that each identifier is labeled with its source. It also discloses the cascading internal lookups. 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 dense and information-rich, but it is organized as block paragraphs rather than structured lists. Every section adds value: example queries, purpose, supported types with specifics, graceful degradation, and efficiency note. It is longer than a minimal summary but not wasteful. The lack of bullet points for the two entity types makes it slightly harder to parse, but it remains appropriately sized for a tool with this 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 absence of an output schema, the description carries the full burden of explaining return values, which it does thoroughly: it lists the exact identifiers returned (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand), mentions the ownership hierarchy, describes the `unresolved` field, and even includes a citation format for drugs. It also covers failure/partial scenarios. This is exceptionally complete for a tool with no output schema.

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

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

The schema already covers 100% of parameters, so the baseline is 3. The description adds meaningful context by explaining the acceptable inputs for each type (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company; 'brand or generic name' for drug) and by clarifying output semantics (unresolved list, source labels). It also clarifies that FIGI is returned only when a ticker is implied. This adds value beyond the schema, though the schema already provides the core 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 starts with concrete example queries ('What's the ticker for…' / 'find the CIK for…') and then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly identifies the resource (entity names → identifiers) and the action (resolve), and distinguishes itself from sibling tools by noting it produces IDs that other tools require.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' This is a clear directive on when to invoke this tool versus others. It also adds that 'using resolve_entity replaces 2-3 manual lookups,' implying it should be preferred over chaining multiple lookups. The description covers both company and drug types, making it actionable for the main use case.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds meaningful behavioral context by revealing it 'Probes each entity with ai_visibility_check' and that it returns a ranked list with score, confidence, and signal density, which goes beyond what annotations indicate. However, it does not discuss rate limits or the number of probes made, so the bar is not fully met.

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

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

The description is concise, with three sentences each contributing unique value: the core action and method, a concrete use case, and the output structure. It is front-loaded with the main verb and resource, and contains no redundant or filler content.

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

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

With no output schema, the description compensates by clearly summarizing the return format (ranked list with score, confidence, signal density). It covers the tool's purpose, usage context, and methodology. While it could detail the number of probes or error conditions, the combination of detailed schema annotations and a rich description makes it largely complete for the tool's complexity.

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

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

Schema coverage is 100%, with each parameter already described. The description adds minimal extra meaning, merely echoing the entities behavior (first entry as subject) already present in the schema. Per rubric, baseline of 3 is appropriate when schema carries the semantic load.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the method (probes each entity with ai_visibility_check), the ranking output, and the use case example, distinguishing it from single-entity tools like ai_visibility_check and general comparison 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 explicitly provides context for use: 'Useful for competitive AI-marketing audits' and an example query. It also names the underlying probe tool (ai_visibility_check), implying single-entity use should go there, but it does not explicitly exclude alternatives or provide a 'when not to use' section, so it stops short of a perfect score.

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, idempotent, and non-destructive behavior; the description adds substantial execution context: it fans out to external APIs, returns a specific summary block, and degrades gracefully when bundlephobia times out (5-30s first measurement, sources_failed field). 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 every sentence is information-dense: composite behavior, invocation triggers, return fields, ecosystem scope, and failure semantics. It is front-loaded with the core purpose before diving into details, and no sentence is 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?

With no output schema, the description carries the full burden of explaining return values and does so by enumerating the summary block fields and listing additional outputs (per-advisory details, links, recent alternative versions). It also covers edge cases such as timeouts and non-NPM ecosystems, making the tool's behavior fully understood.

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 goes slightly beyond by adding the ecosystem constraint 'NPM ecosystem only in v1' and clarifying that version defaults to latest via 'is_latest' context. Most parameter semantics still reside in the schema, but this added constraint earns a 4.

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

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

The description opens with a clear verb+resource: 'Composite ... check in ONE call' and explicitly names the data sources (deps.dev, bundlephobia). It states the user-facing purpose ('should I add this npm package to my project') in plain terms, making it unambiguous what the tool does and how it differs 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?

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'—direct when-to-use guidance. It also names the alternative for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving clear boundary conditions.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the behavioral detail that it returns articles with title, summary, URL, and publication date, which is useful 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 short sentences: the first states the primary action, the second the return fields. It is front-loaded and contains zero wasted words.

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

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

With only two parameters, both fully described in the schema, an output schema present, and annotations covering safety, the description provides enough context to select and invoke the tool correctly. No critical information 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 input schema already provides full descriptions for both parameters (query and limit) with 100% coverage. The description's keyword reference adds no new parameter semantics, so it stays at the baseline.

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

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

The description succinctly states that the tool searches spaceflight news articles by keyword, which is a specific verb-resource pair. It distinguishes itself from siblings like get_articles by focusing on keyword-based search over a defined article set.

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: use it to search spaceflight news articles by keyword. However, it does not mention any alternatives or exclusive conditions (e.g., when to use get_articles instead), 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 the tool is read-only, idempotent, and non-destructive, but the description goes well beyond this by disclosing the embedding model (BGE-base-en), similarity metric (cosine), windowing strategy (500-char overlapping windows), character cap (200K), and truncation behavior (flagged). It also specifies that results include character offsets and similarity scores, giving the agent a clear model of expected behavior.

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

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

The description is front-loaded with the core purpose, then expands into usage guidance, pairing with a sibling, and technical details. Every sentence adds distinct value—use case, return value, workflow, model, cap—without fluff 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?

Given there is no output schema, the description compensates by explaining exactly what the agent gets back (passages, character offsets, similarity scores) and how the tool behaves under size limits. It also covers the workflow relationship with ask_pipeworx_grounded, making it sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for all three parameters, so the schema already explains text, query, and limit. The description adds context by clarifying 'text' means already-pulled fetched content, 'query' is a natural-language request with examples, and the cap behavior. This enriches the schema without repeating it verbatim.

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 ('semantic search') and clearly identifies the resource ('inside a fetched record'), distinguishing it from siblings like search_articles by emphasizing it operates on already-pulled text rather than external sources. It also states the return format (top-N passages with offsets and scores), making the purpose unambiguous.

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

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

The description explicitly states when to use the tool ('Use when the record is too big to cram into the prompt') and explains the benefit (saves context, returns only relevant passages). It mentions a sibling tool (ask_pipeworx_grounded) as a paired workflow, but does not explicitly state when not to use it or list direct alternatives as preferred in some cases.

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?

With annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) already declaring mutation and idempotency, the description adds valuable context: returns subscription id, requires authenticated account (anonymous/BYO cannot persist), and details delivery caveats (SMS cap, phone verification, webhook auto-disable). Does not contradict annotations.

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

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

The description is dense but well-structured: purpose first, then auth requirement, then types with examples, then delivery channels. Every sentence adds useful information. It is long but appropriate 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?

For a tool with 3 parameters, nested objects, and multiple subscription types, the description covers return value, auth prerequisites, all supported types with examples, delivery channels, and operational constraints. The schema fills in remaining details, and no output schema is needed given the return value is stated.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining individual item codes (e.g., items:["5.02"] = officer change) and giving concrete examples (e.g., topic:"fed", series_id:"UNRATE"). This enhances parameter understanding without repeating schema text.

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

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

The description states a specific action ('Create a proactive monitoring subscription') on a specific resource ('live-data event stream'), and distinguishes from sibling tools like list_subscriptions and unsubscribe. It clearly indicates the tool's primary function.

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

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

The description provides strong context: requires OAuth account, supported subscription types with examples, delivery channels, and prerequisites like verified phone for SMS. It doesn't explicitly mention 'use this instead of X', but the context is sufficient for selecting this tool over siblings. Minor gap: no 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it returns category-bucketed examples from a live catalog, supports optional topic filtering, and serves an onboarding role. 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 front-loaded with sample queries that aid intent matching. Each part serves a purpose, though the opening list of example phrasings is slightly redundant and could be tightened without losing meaning.

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

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

Since no output schema exists, the description adequately explains the return value structure (category-bucketed examples with tool + argument shapes) and the parameter behavior (omit vs topic focus). For a simple one-parameter tool, it covers all necessary 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?

The input schema covers the sole parameter with 100% completeness, including the omit-for-spread behavior. The description provides examples ('finance', 'pharma', 'betting') but essentially reiterates the schema's own description, adding minimal new 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 clearly states the tool is the onboarding entry point for discovering what Pipeworx can do, returning category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by saying 'Use this FIRST' and referencing meta-tools like ask_pipeworx, entity_profile, and 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?

Explicitly instructs to use this FIRST when uncertain about Pipeworx capabilities or to learn how to call meta-tools. This implies when not to use it (when you already know what to ask) and names alternatives (ask_pipeworx, entity_profile, compare_entities), giving clear context and exclusions.

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

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

The description adds meaningful behavioral details beyond the annotations: ownership enforcement, row deactivation instead of deletion, and the impact on recent_alerts. These specifics clarify the tool's behavior in a way that annotations alone do not fully 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?

Two sentences, front-loaded with the primary action, and every sentence serves a purpose (action, ownership, side effects). 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?

For a one-parameter tool, the description covers purpose, ownership, and side-effect on historical events. However, it does not mention the return value or error cases (e.g., invalid id or unauthorized attempt), which would be useful given the absence of an output schema. Overall, it is nearly complete for the tool's simplicity.

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

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

Schema coverage is 100%, with the parameter fully described as the subscription id returned by subscribe. The description only says 'by id', adding no extra semantics beyond the schema, so the baseline of 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 uses a specific verb (Cancel) and resource (a subscription by id), clearly naming the action. It also distinguishes from siblings by noting ownership enforcement and the deactivate-not-delete behavior, making it unique among subscription-related 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 implies when to use the tool (to cancel a subscription you own) and provides contextual cross-reference to recent_alerts for historical availability. It does not explicitly name alternatives like list_subscriptions or when not to use, but the ownership constraint and deactivation note give clear practical guidance.

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

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

The annotations already declare readOnly/idempotent/non-destructive, but the description adds crucial behavioral semantics: it enumerates the verdict values, distinguishes could_not_verify (check did not happen, with verification_error) from unsupported (no source exists), and explains that could_not_verify must not be presented as evidence. It also reveals the exact percent-delta math for financial claims and the grounded response with verbatim evidence, going well 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 a dense paragraph but every sentence contributes: query triggers, usage rule, two routing paths, return contract, caller warnings, and efficiency justification. It is not padded, but the length is considerable; a bit more structure (e.g., bullets for the caller caveats) would make it even easier to parse, so it doesn't reach top score.

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 carries the full burden of explaining returns, and it does so thoroughly: verdicts, evidence citations, reasoning, error semantics for could_not_verify, and unsupported behavior. It also covers both routing paths and the tolerance parameter's behavior, so an agent has complete context to call 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?

Both parameters are already fully described in the schema (100% coverage), and the description adds extra meaning by explaining that tolerance_pct overrides the wording-implied tolerance, defaults to a cap of 5, and suggests 1–2 for hallucination detection. This provides practical guidance beyond the schema, so the score is 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 explicitly states the tool verifies natural-language factual claims ('fact check', 'verify the claim that…') and distinguishes itself from related tools by describing its two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for others). It also positions it as replacing 4–6 sequential calls, clarifying the core purpose.

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 explicit direction: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the conditions for the two internal paths and notes that any other factual claim automatically falls through, making it clear this is the single tool for claim verification. While it doesn't explicitly name alternatives to avoid, the usage context is strong.

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