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, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral context: routing across a large tool inventory, filling arguments automatically, returning structured answers, and using stable pipeworx:// citation URIs. No contradiction with the annotations.

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

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

The description is front-loaded with a strong preference directive, followed by a scannable category list, concrete routing behavior, and useful example queries. It is dense but every clause contributes meaningful information, with no wasted or redundant sentences.

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

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

For a simple one-required-parameter tool with no output schema, the description is sufficiently complete: it explains what the tool does, what kinds of questions to send, what happens to the question, and what the answer format includes. The examples and coverage list make agent invocation well specified.

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

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

The schema documents the primary `question` parameter and all five aliases with 100% coverage, so the description does not need to redefine them. It adds example phrasings and trigger words, but no deeper parameter-level semantic detail beyond what the schema already provides.

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

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

The description clearly states a specific purpose: routes natural-language questions to one of 5,756 tools across 1,504 sources and returns structured answers with citation URIs. It also gives a strong sense of coverage via concrete domains, but it does not distinguish ask_pipeworx from the sibling variants ask_pipeworx_beta and ask_pipeworx_grounded.

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 to prefer this tool over web search for factual, current, or historical questions and provides trigger phrases plus examples. It gives clear when-to-use guidance, but it does not mention when to choose sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, and it does not list exclusion cases such as non-factual or creative requests.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is already covered. The description goes beyond annotations by disclosing that this is an experimental edge with candidate routing improvements that may change live, that no candidate is currently active, and that it 'falls back to nothing' — meaning it is a fully working router, not a degraded stub. This experimental nature is valuable behavioral context not present in the annotations.

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

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

The description is a single solid paragraph that front-loads the beta identity and current-state equivalence to ask_pipeworx, then explains the routing experiment and reassures that this is a full working router. It is slightly dense but every sentence earns its place: identity, status, usage guidance, and fallback behavior are all covered without 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 single-parameter routing tool with 100% schema coverage and read-only/idempotent annotations, the description is nearly complete. It explains the experimental nature, current parity with the stable router, and how results are used. The only minor gap is that it doesn't describe the response shape in detail, but since there is no output schema and the description says the response shape is identical to ask_pipeworx, an agent familiar with the sibling can infer it. The beta/non-stability caveat is the most important context and it is fully covered.

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

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

Schema description coverage is 100%, so the schema already documents that question is the single required parameter and lists five aliases (q, text, input, query, prompt) all mapped to question. The description confirms the same arguments as ask_pipeworx but doesn't add new semantic detail about parameter usage beyond what the schema provides. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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

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

The description clearly states this is the beta version of ask_pipeworx, a universal router with the same 5,756 tools and arguments. It explicitly differentiates itself from the stable ask_pipeworx by noting candidate routing improvements and that it currently matches ask_pipeworx exactly when no candidate is active. This gives an agent a precise understanding of what the tool is and how it relates to its sibling.

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 it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router for comparison purposes. It also notes that results are compared against the stable router to decide merges, giving clear context on when to choose this tool over ask_pipeworx. This is strong guidance for tool selection.

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

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

Beyond the annotations (read-only, idempotent, open-world, non-destructive), the description reveals critical behavioral traits: it extracts answers solely from tool results, returns a structured evidence object with verbatim quotes, and explicitly refuses with categorized refusal_reason values when data is insufficient. This significantly exceeds what annotations alone convey.

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

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

The description is dense but well-organized, front-loading the core purpose and using structured lists for return shapes and refusal reasons. The inclusion of precise source/tool counts and detailed response contract is justified for a high-stakes tool, though slightly longer than strictly needed.

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

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

The description completely covers what the tool does, when to use it, how it differs from ask_pipeworx, what success and refusal responses look like, and the cost/performance trade-off. With no output schema, the explicit return format and refusal reasons are essential and provided thoroughly.

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 the question parameter fully described including aliases. The tool description adds no additional parameter-level meaning—it only refers to 'fills arguments' generically—so the schema carries the semantics and baseline 3 applies.

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

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

The description clearly identifies the tool as a grounded, hallucination-resistant answer mode for high-stakes reads, explicitly contrasting it with ask_pipeworx. It specifies the resource ('Pipeworx') and the behavioral verb ('answers using only tool result contents'), making the purpose unmistakable and distinct from siblings like validate_claim 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 provides explicit usage guidance: use when an answer will be quoted, cited, or acted on, especially for financial, legal, or medical facts, and prefer ask_pipeworx for casual lookups. This directly addresses when to choose this tool over its sibling and even states the cost trade-off (extra LLM call), leaving no ambiguity.

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

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

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 adds substantial behavioral detail beyond the annotations: account requirements, paid plan gate, parallel decomposition across 5,756 tools, return packet contents, explicit gaps[] rather than invented answers, resolvable citation URIs, contradiction scanning, semantic excerpting, and expected latency. There is no contradiction with the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint 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 carries operational value for the agent: prerequisites, when to choose alternatives, output format, citation resolution, depth semantics, and timing. Critical guidance such as account requirement and when to use ask_pipeworx is front-loaded.

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

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

Given there is no output schema, the description thoroughly covers return semantics: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers latency, depth behavior, and usage boundaries, making the tool fully callable by an agent with minimal ambiguity.

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

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

Although schema coverage is 100%, the description adds significant meaning: it explains the behavioral difference between quick/standard/thorough, states the default, notes the paid requirement for thorough, and clarifies that the 'question' parameter is meant for broad, multi-part, natural-language research questions. This goes well beyond the schema descriptions.

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

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

The description states a specific action and resource: 'Grounded multi-source research across Pipeworx's 1504 STRUCTURED data sources' in one call. It clearly distinguishes itself from open-web search and names alternatives like ask_pipeworx, so an agent can tell it apart 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?

Explicit usage guidance is provided: use it for broad/multi-part questions over structured data, use ask_pipeworx for single lookups, and use ask_pipeworx when not signed in because deep_research requires an account. It also explains when depth levels are appropriate, including the paid 'thorough' tier.

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 goes well beyond the readOnly/openWorld/idempotent annotations: it discloses the fan-out across SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, GDELT/GNews, and GLEIF; explains soft-failure for the USPTO sunset; states that an empty fda_products section is expected for non-biologic companies; and clarifies that sources_used/sources_failed distinguish real no-data from bugs. This is rich behavioral context without contradicting annotations.

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

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

The definition is long but well-structured: purpose and usage rule come first, then source fan-out, then return-field semantics, then input forms. Some information, like type interchangeability, is redundant with the schema, but the length is largely justified by the tool's complexity and by the absence of an output schema.

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 burden of explaining return values, and it does so exhaustively: cik, resolved_from/resolved_to, recent_filings URIs, fundamentals sorting, patents soft-fail, federal contracts, FDA products with expected empties, H-1B hiring, news fallback, LEI, and sources_used/sources_failed. It also specifies edge-case behavior for private companies, making the tool fully callable.

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 the baseline is 3. The description adds meaning by clarifying that 'type' accepts 'company' or 'ticker' interchangeably, that 'value' can be a ticker, zero-padded CIK, or company name, and that names resolve via SEC EDGAR matching. This helps an agent construct valid calls beyond what the schema states.

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 a crisp definition: 'full cross-source profile of a US public company in ONE parallel call.' It identifies the resource (US public company), the action (profile/research/brief), and differentiates itself from single-pack SEC/XBRL/news lookups, which helps an agent distinguish it from sibling tools like compare_entities 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?

Explicit when-to-use guidance is front-loaded: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names the alternative ('single-pack lookups') and describes expected behavior for non-matches, such as private companies returning resolved:false. This gives clear decision-making context.

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

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

Annotations already 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?

Beyond readOnly and idempotent annotations, the description discloses key behavioral traits: the matcher is keyword/word-overlap based and never pairs legs with unknown metric_type or match_subtype; spreads are gross because Kalshi fees are not modeled; temporal_alignment null means 'could not be computed,' not aligned; and compatibility_codes can be non-empty even when matched_pairs>0. This is exemplary disclosure of limitations.

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 organized into labeled sections and front-loads the core purpose, but it is very long and contains redundancy, such as restating that temporal_alignment_unknown means the resolution month could not be parsed and that null is not equivalent to alignment. Every sentence is informative, but the text could be tightened without loss of 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?

With no output schema, the description carries the full burden of explaining the response, and it does: it lists leg-by-leg prices, spread array contents, compatibility fields, skipped counters, fees_note, and temporal_alignment semantics. It also sets expectations about the rarity of real spreads. Nothing needed for correct use appears 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 describes all three parameters with 100% coverage. The description adds semantic value by explaining that topic is a pre-mapped shortcut, that the two explicit parameters override the topic-mapped side, and that both modes run the identical token-overlap matcher. This goes beyond the schema's basic field 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 opens with a clear statement of what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the two venues, the quantity produced (spread), and the condition for validity (same resolving question), which distinguishes it from single-venue siblings like polymarket_edges.

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

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

The description explains when to use each of the two modes (topic shortcuts vs explicit event ticker) and how the explicit parameters override the topic mapping. It also warns that most pre-mapped topics return compatibility_warning today, setting expectations. However, it does not explicitly contrast this tool with sibling tools like polymarket_arbitrage or state when not to use it in favor of an 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?

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?

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavior beyond that: graceful degradation ("if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return"), ambiguity handling ("when a name matches more than one instrument it asserts nothing and returns figi_candidates"), explicit unresolved reporting ("stated explicitly under unresolved rather than omitted"), and internal endpoint cascading. No contradiction with annotations.

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

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

The description is front-loaded well — triggering queries and the "Use FIRST" rule appear immediately — and nearly every sentence carries useful information. However, it is a single dense run-on paragraph with deeply nested parentheticals (the company-type explanation buries key facts like figi_candidates and unresolved inside long clauses), which makes key extraction harder than it should be for an agent.

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

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

For a complex, two-type tool with no output schema, the description covers inputs, outputs per type, failure modes, ambiguity, and degradation remarkably well. Remaining gaps: the drug type receives comparatively thin treatment (no ambiguity or resolution-failure detail) and the overall return shape is never described, but these are minor given the depth already present.

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 supplies examples (AAPL, 0000320193, "ozempic") plus the entity-name-only caution for bonds. The description goes beyond the schema by adding ISIN as an accepted input form, explaining the GLEIF ISIN-to-LEI mapping for non-US issuers, and clarifying that non-equity instruments without tickers still resolve — genuinely new parameter meaning beyond 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 states a specific verb and resource: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It enumerates concrete triggering queries ("What's the ticker for…" / "find the CIK for…") and the two supported types with their outputs, distinguishing itself from siblings like entity_profile and compare_entities which presume an ID or entity, not a name-to-ID resolution.

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

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

Provides an explicit when-to-use rule: "Use FIRST whenever you have a name but need an ID," plus an efficiency argument ("using resolve_entity replaces 2-3 manual lookups"). It does not name a specific sibling alternative or state exclusion conditions (e.g., what to use when you already hold an ID), so some routing inference is left to the agent.

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.