Spaceflight News

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds details: probes LLMs, returns per-model data with score/confidence/signals, mentions Anthropic call payment model. No contradictions. Adds useful behavioral context beyond annotations.

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

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

Four sentences, front-loaded with purpose, no redundant information. Every sentence adds value.

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

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

Given 4 parameters and no output schema, description explains return structure (per-model + combined view), scoring range, and model selection. Sufficient for agent to understand tool behavior.

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%. Description adds value by specifying default model for models parameter, explaining that _apiKey is passed through to Anthropic, and noting context helps disambiguate. This exceeds 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?

Description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It distinguishes from siblings by its specific focus on AI visibility scoring, not general research or entity profiling.

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

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

Description mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default model and BYO key for Anthropic. However, it does not explicitly contrast with similar sibling tools like scan_competitor_ai_presence.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those hints: it routes to one of 5,710 tools, fills arguments automatically, and returns answers with stable pipeworx:// citation URIs. It does not discuss failure modes or rate limits, but the core safety profile is already covered by 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 unnecessarily long and contains duplicated blocks: the 'START HERE for most questions' sentence and the full example list appear multiple times. While the opening is front-loaded with useful guidance, the repetition means many words do not earn their place.

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 a single free-text question parameter and no output schema, the description supplies enough context: what domains it covers, how to phrase queries, what routing behavior to expect, and what kind of answer is returned. It is missing limited edge-case detail such as unsupported topics or error behavior, but it is functionally complete for selection and invocation.

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

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

The schema covers 100% of parameters and documents all six as aliases for a single natural-language question, so the baseline is solid. The description adds value by illustrating the range of acceptable questions with examples such as 'current US unemployment rate' and 'active clinical trials for GLP-1', which helps an agent compose the question parameter correctly.

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

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

The description clearly identifies the tool's role: answering factual questions about real-world entities, events, and numbers by routing to verified sources and returning cited structured answers. It names concrete domains and example queries, making it easy for an agent to recognize what ask_pipeworx is for and how it differs from a generic web search path.

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

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

The description gives explicit trigger phrases like 'what is', 'look up', 'find', 'get the latest', and 'how much', and instructs agents to prefer this tool over web search even when web search could answer. It also provides a clear alternative: use deep_research for broad/multi-part questions that need to fan out across many sources.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that candidate routing improvements may be live, that none are active as of the stated date, and that it currently matches ask_pipeworx exactly. It also clarifies it does not fall back to a stub. This adds meaningful behavioral context, though it does not cover error behavior or latency.

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 roughly 70 words across four sentences, front-loading the key facts: it is the beta version, identical to ask_pipeworx, and a universal router. The specific tool count and retirement date add useful precision, though the 'Falls back to nothing' phrasing is slightly awkward and could be misinterpreted.

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 stateless router with no output schema, the description covers what the tool is, its current behavior, and how to use it, and points to ask_pipeworx for the response shape. Since the sibling tool name is visible, the agent can resolve the response format; a fully self-contained description would explicitly describe the return payload, but this is acceptable given the sibling 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 has 100% description coverage — each of the six parameters is described as either 'Alias for question' or 'The question to ask.' The description only says 'same arguments' as ask_pipeworx, which adds no parameter-level meaning beyond what the schema already provides, so the baseline score 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 states a specific function (a universal router) and resource scope: identical to ask_pipeworx with the same 5,710 tools, arguments, and response shape. It clearly distinguishes itself from the stable ask_pipeworx sibling by being the beta/experimental edge, so there is no ambiguity about what it is.

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 guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the context of candidate routing evaluation and explicitly says it 'is a full working router', so the agent knows when it is safe to use and what the alternative (stable ask_pipeworx) is for.

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

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

The description discloses non-obvious behavior beyond the annotations: refusal semantics with a specific refusal_reason enum, verbatim evidence extraction, the success/refusal response contract, and the extra LLM call cost. Annotations already signal read-only and idempotent, so the description adds meaningful behavioral context rather than repeating annotation data.

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

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

The description is dense but efficiently organized: purpose, routing behavior, return contract, refusal contract, usage conditions, and cost tradeoff. Every sentence carries information needed for correct selection and invocation, with no 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?

There is no output schema, so the detailed success and refusal return contracts in the description are essential and fully provided. With 100% parameter schema coverage, read-only annotations, and clear sibling differentiation, nothing critical is missing for an agent to invoke and interpret this 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 description coverage is 100% for the 6 parameters, so the schema already documents each parameter. The description does not add parameter-level detail beyond saying it fills arguments internally, which is not needed given full schema coverage. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: a hallucination-resistant, grounded answer mode for high-stakes reads. It clearly states what the tool does — route, fetch, then extract an answer only from the tool result — and explicitly contrasts itself with ask_pipeworx, which distinguishes it from its closest 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?

It gives an explicit 'Use whenever' condition: when an answer will be quoted, cited, or acted on and the agent must not invent facts. It also names ask_pipeworx as the alternative for casual lookups and states the cost tradeoff, so the agent knows exactly when to select this tool versus its sibling.

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 reveals extensive behavioral details beyond annotations, including low-confidence match handling, closed market detection, wide-spread warnings, cancellation rule parsing, and backfill mechanisms for news sources. It fully discloses safety measures and error paths, with no contradictions to 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 and dense, though well-structured with explicit sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). While the first sentence is front-loaded with purpose, the overall length may hinder quick parsing. The complexity justifies some length, but it is 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?

Despite having no output schema, the description fully compensates by detailing response shapes, resolver behavior, evidence keys, news field structure, and safety mechanisms. It covers all edge cases (closed markets, low confidence, wide spreads, cancellation rules) and provides complete guidance for a complex tool.

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

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

With 100% schema coverage, the description adds significant meaning: it explains that 'market' accepts slugs, URLs, or question text; defines 'depth' with quick/thorough examples; and details when to use 'include_raw' (recommended false for small responses, true for full payloads). 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 clearly states the tool's purpose: to research a Polymarket bet by pulling Pipeworx data in one call. It lists specific input types (slug, URL, question text) and provides extensive examples. It distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on data gathering for a single bet.

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 usage scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides detailed guidance on when to inspect certain fields (e.g., market_match_confidence). It also explains the depth parameter for quick vs. thorough analysis, giving agents clear trade-offs.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral detail: source (EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, result sorting by primary metric, and inclusion of citation URIs. No contradiction with annotations; this is exemplary transparency.

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

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

The description is front-loaded with example triggers, making it easy for an agent to match. It is slightly long but every sentence adds essential information (data sources, sorting, return format, efficiency claim). A minor trim could improve conciseness, but the structure is effective.

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

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

Given the tool's complexity (two entity types, multiple data sources), the description covers what data is retrieved per type, how results are sorted, and the return format (paired data + citation URIs). It lacks mention of error handling or invalid values, but overall it is sufficiently complete for an agent to use 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%, so the baseline is 3. The description adds value by explaining the enum values ('type' can be company or drug, with what data each pulls), and clarifies the 'values' parameter with specific formats (tickers/CIKs for company, drug names) and the min/max items constraint. This goes beyond the schema's 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 starts with concrete natural language triggers (e.g. 'X vs Y', 'which is bigger'), then explicitly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It also distinguishes from siblings by advising to prefer this over sequential single-pack lookups. This makes purpose exceptionally clear.

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

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

The description gives explicit when-to-use examples ('head to head', 'rank these companies') and commands 'ALWAYS PREFER' over alternatives, providing clear usage context. It does not specify when not to use it, but the positive guidance is strong enough for a 4.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses substantial behavioral context: authentication and tier gating ('depth:"thorough" needs a paid plan'), latency ('Expect 15-60s... up to ~90s'), the honesty mechanism ('explicit gaps[] for facets the data couldn't answer (never invented)'), citation fetchability guarantees ('a citation you get back is always fetchable'), contradictions[] for standard/thorough, and semantic excerpting ('not head-truncated'). This far exceeds the annotation baseline and does not contradict any hint.

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 information-dense — every sentence carries operational value, and the most critical constraint (account requirement, fallback to ask_pipeworx) is front-loaded before the mechanics. It loses one point because the middle passage on hop semantics reads garbled and winding (text-artifact interference), which slightly impedes parsing of the depth-level distinctions, though the overall structure is still effective.

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

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

For a complex tool with no output schema and only 2 params, the description compensates admirably: it details the return structure (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gap and contradiction behavior, hop semantics per depth, excerpting policy, latency bounds, and auth prerequisites. Nothing an agent needs to invoke or interpret the tool correctly is left undisclosed, satisfying the complexity of a parallel-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?

Schema description coverage is 100% (both question and depth are documented in the schema), so the baseline is 3. The description adds genuine value beyond the schema by disclosing that depth:"thorough" requires a paid plan, mapping each depth value to its hop behavior, and confirming that broad/multi-part questions are the intended input for question. This tier-gating and behavioral mapping is information the schema alone does not provide.

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: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources... in ONE call' that 'Decomposes your question into focused facets, routes each to the right one of 5,710 tools IN PARALLEL, and returns a findings packet.' It explicitly differentiates from siblings by declaring 'this is NOT open-web search' and contrasts itself with ask_pipeworx ('For a single lookup use ask_pipeworx instead'), so an agent can distinguish it from compare_entities, entity_profile, and ask_pipeworx without opening their schemas.

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

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

Usage guidance is explicit and actionable: 'If you are not signed in, use ask_pipeworx instead — it works on every tier,' 'Best for broad/multi-part questions over structured data,' and 'For a single lookup use ask_pipeworx instead.' It also states the exclusions ('this is NOT open-web search') and provides concrete example queries, leaving no ambiguity about when to select this tool versus its named 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=true, destructiveHint=false, idempotentHint=true. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This enriches the behavioral understanding beyond what annotations provide.

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

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

The description is moderately long but well-structured: purpose first, then examples, then usage guidance. Every sentence contributes value. Could be slightly trimmed, but overall it's efficient and front-loaded.

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

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

Given the tool's function (discovery), 6 parameters with full schema coverage, and no output schema, the description covers behavior, return content, when to call, and examples. Nothing essential is missing for an agent to use it 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 description coverage is 100% (all 6 parameters have descriptions in the schema). The description does not add new semantic meaning for parameters beyond the schema; it only gives aliases and examples. Baseline is 3, which 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 'Find tools by describing the data or task' — a specific verb+resource. It lists numerous example domains (SEC filings, FDA drugs, etc.), distinguishing this from sibling tools that perform specific tasks (e.g., search_articles, get_article). The purpose is unmistakably clear.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and implies when not to (when the tool is already known). No alternative tool is directly mentioned, but the instruction is clear enough.

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

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

Discloses internal fan-out across multiple sources, patent soft-failure, return structure including URI pattern for filings, and limitations. Annotations already indicate safe read-only behavior; description adds valuable operational details without contradiction.

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

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

Description is relatively long but front-loaded with examples and key sentence about preference. Each sentence adds value; slight redundancy could be trimmed, but overall efficient for the complexity.

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

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

Despite no output schema, description details all returned data fields and sources. Covers inputs, limitations, and error conditions (patent fail). Complete for an agent to understand tool's capabilities and context.

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

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

Schema coverage is 100% and description adds further context: value accepts ticker or zero-padded CIK (not names), type is restricted to 'company'. This enhances understanding beyond the schema.

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

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

Description clearly states it provides a full cross-source profile of a US public company in one parallel call. Uses concrete examples like 'Tell me about X' and distinguishes from siblings like resolve_entity by specifying input requirements.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views and advises using resolve_entity if only a name is available, providing clear when-to-use and alternative guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive operation. The description adds context about use cases (clearing sensitive data, stale context), but does not fully disclose potential consequences like lack of undo or error handling for missing keys. Still, it provides helpful behavioral context beyond annotations.

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

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

The description is extremely concise—two sentences that cover action, usage context, and pairing. Every sentence adds value with no redundancy or filler.

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

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

For a simple, single-parameter tool with no output schema, the description is nearly complete. It covers purpose, usage guidelines, and relationships. It could mention error behavior (e.g., if key doesn't exist) or permanence, but these are minor omissions.

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

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

With 100% schema coverage and only one parameter ('key'), the schema already explains that the key is the memory to delete. The description adds no additional semantic meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's action ('Delete a previously stored memory by key') and identifies the resource ('memory'). It also distinguishes itself from sibling tools by pairing with 'remember' and 'recall', making its role unique.

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 conditions for use ('when context is stale, the task is done, or you want to clear sensitive data') and references alternative tools ('Pair with remember and recall'). This offers clear guidance on when to invoke this tool versus others.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's main role is to add behavioral context. It does so by detailing the process (fetches, extracts, emits) and noting the output is a single text blob. It does not discuss potential failures (e.g., timeouts on large pages) or rate limits, but the core behavior is transparently described.

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 concise: two substantive sentences followed by a bulleted list of use cases. Every sentence serves a purpose - stating the action, the target audience, the process, and the output format. No wasted words. The most critical information is front-loaded.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is fully complete. It explains what the tool does, how it works, what it produces, and when to use it. An AI agent has all necessary information to decide when to invoke this tool and what parameters to provide.

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

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

Schema coverage is 100% - both 'url' and 'max_links' are described in the input schema. The description does not add any new information about parameter semantics beyond what the schema already provides. For instance, it does not clarify the format of 'url' or the behavior when 'max_links' is omitted. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the target AI crawlers (ChatGPT, Claude, Perplexity), the extraction process (page fetch, title/description/key links), and the output format (standard llms.txt markdown). The 'Useful for' section explicitly lists three application scenarios, which helps differentiate it from siblings like scan_competitor_ai_presence 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 clear context on when to use the tool (getting a client's site indexed, drafting for own project, auditing competitors) but lacks explicit guidance on when not to use it or what alternatives exist. While the use cases are well-articulated, the absence of exclusionary or comparative references (e.g., 'if you need a full crawl, use deep_research instead') prevents 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 indicate read-only, idempotent, and non-destructive. Description adds that it returns full untruncated summary and associated data, and that it is keyless (no authentication needed). This provides useful behavioral context beyond annotations.

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

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

The description is two sentences with no wasted words. Key action and resource are front-loaded, and supplementary details are succinctly appended.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers what the tool returns (full summary, launches, events) and its keyless nature. No gaps identified.

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

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

Schema coverage is 100% and describes the parameter as numeric article id from search_articles results. The description reinforces this and adds context about the id's origin, enhancing meaning beyond schema.

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

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

The description clearly states the tool retrieves a single spaceflight news article by numeric id, with untruncated summary and associated launches/events. This distinguishes it from sibling search_articles.

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

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

The description specifies using article id from search_articles results, implying this tool is for retrieving a known article. No explicit when-not-to-use or alternatives are given, but context is clear.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive). Description adds 'Keyless' (no auth) and ordering, which are helpful but not extensive.

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

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

Two concise sentences, front-loaded with key info. Minor waste: 'Keyless' could be integrated, but overall efficient.

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

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

Tool is simple with one optional param and no output schema. Description covers purpose and ordering. Could hint at return structure but sufficient for basic use.

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

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

Single parameter 'limit' is fully described in schema (default, max). Description adds no additional parameter detail. Baseline 3 for 100% 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?

Description clearly states verb (list), resource (long-form spaceflight mission reports), and ordering (newest first). Distinguishes from siblings like get_article and search_articles by specifying scope and length criteria.

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?

Implied usage for browsing recent reports, but no explicit when-to-use or when-not-to-use guidance. Missing comparison to search_articles or other listing tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description's job is lighter. It adds that the tool lists sources and the API version, and importantly states 'Keyless', which clarifies authentication requirements. No contradictions with annotations.

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

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

Two concise sentences with no wasted words. Each sentence serves a purpose: the first states what the tool does, the second gives usage guidance and keyless info. Front-loaded with the core action.

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

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

Given the tool's simplicity (no input parameters, no output schema, low complexity), the description covers the essential: what is returned, how to use the output, and authentication. Could optionally mention if there is pagination or rate limits, but not necessary for this simple 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 tool has zero parameters, and the schema description coverage is 100% (empty). The description adds meaning beyond the schema by explaining what the output contains (sources and API version) and how it can be used. This fully compensates for lack of parameter details.

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

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

The description clearly states the verb 'list' and the resource 'every news source' plus API version. It distinguishes from sibling tools like search_articles by explicitly mentioning using the names to filter that tool. The purpose is specific and unambiguous.

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

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

The description provides a clear usage scenario: use the names to filter search_articles. It also notes 'Keyless' indicating no authentication needed. However, it does not explicitly exclude other contexts or mention when not to use this tool, leaving some guidance implicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds specific return fields and mentions active subscriptions. 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 output, second gives usage. No superfluous text, 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?

Simple tool with clear purpose, one optional param, and listed return fields. Sibling context available. Description is sufficient for an agent to understand when and how to use.

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

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

Schema covers 100% of parameters with descriptions. Description adds no new parameter information beyond the schema, but mentions return fields as context.

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

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

Clearly states verb (list), resource (subscriptions), and scope (caller's active). Lists return fields. Distinguishes from siblings like subscribe/unsubscribe.

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

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

Explicitly says when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context, though 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?

Discloses rate limiting (5 per identifier per day), free usage, no quota impact, daily digest reading, and the claim_token flow for follow-up. All annotations are false (no safety profile), so this description carries the full burden and does so richly.

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?

Though lengthy, every sentence earns its place: purpose, when-to-use, exclusions, claim_token flow, roadmap impact, and rate limit. The structure front-loads the core verb and then layers usage context logically. 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?

Covers purpose, use cases, exclusions, claim_token follow-up mechanics, rate limits, and return behavior (via claim_token). No output schema exists, but the description sufficiently explains what the tool returns—both initial claim_token and later status updates. Fully complete for a complex feedback-capture tool.

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

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

Schema coverage is 100% (all parameters described), so baseline is 3. The description adds meaningful context beyond the schema: explains the claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs users not to paste the end-user's prompt. This elevates it 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 opens with a clear, specific purpose ('Tell the Pipeworx team something is broken, missing, or needs to exist') and explicitly distinguishes from siblings by stating it is ONLY for tools served by this Pipeworx connection. This prevents confusion with other MCP server feedback 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 when to use (bug, feature/data_gap, praise) and when NOT to use (other MCP servers), going so far as to name the alternative action ('file it with that server instead'). This provides unambiguous decision 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. The description adds value by noting it is self-aggregating from CF analytics-engine, includes no PII, and has caching behavior (5min-1h). No contradictions.

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

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

The description is concise: three sentences plus a bulleted list. Every sentence adds value, and the key action is front-loaded. No redundant or wasteful language.

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 has only one parameter and no output schema, the description is complete. It covers what is returned, caching, data source, and use cases. No gaps remain for this simple reader 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 only parameter 'window' is fully described in the schema (enum, default). The description adds nuance: shorter windows for 'hot right now', longer for 'steady-state demand'. Schema coverage is 100%, but the description enhances understanding.

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

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

The description specifies the tool returns top tools, top packs, and total call volume over a recent window. It uses a specific verb ('Returns') and clearly distinguishes from sibling tools by describing its meta-trend use case.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming popular tool, alignment check) and explains when to choose different windows. It provides clear context for use without needing to mention when not to use.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. Description adds crucial behavioral details: fill check, partition filter (placeholder >20% returns null), semantic anchor for cross-event, and the condition for not trading. No contradictions.

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

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

Description is comprehensive but slightly lengthy; however, it is well-structured with clear sections for each mode and additional details. Every sentence adds value for a complex tool; minor redundancy could be trimmed.

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

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

No output schema provided, so description must cover return values. It does so thoroughly: lists opportunities[] with fields, partition_check structure, and fill_check integration. Covers all key behaviors for a tool of this complexity.

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

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

Schema covers 100% of parameters with descriptions, but description adds significant context: event includes slug or full URL, topic describes seed question and search behavior. The description explains the effect of each parameter mode, beyond schema.

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

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

Description explicitly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and clearly distinguishes its three modes (trending_scan, event, topic). It differentiates well from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also explains when not to use (when fill check shows negative realizable edge) and details prerequisites like slug or topic input.

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, which the description reinforces. The description adds substantial behavioral details: model families, slippage handling, caching (1h at KV level), response structure with diagnostics, and conditions like 'rare-by-design'. No contradictions.

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

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

The description is front-loaded with the core purpose and structured into clear segments. Though verbose (approx. 300 words), every sentence adds value. Minor redundancy exists (e.g., repeated explanation of segments), but overall well-organized 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?

Given 9 parameters, no output schema, and complex behavior (three segments, multiple models, diagnostics), the description is exceptionally complete. It explains return fields (edge_pp_net, kelly_fraction), response structure (by_segment, fed_candidates, diagnostics), and caching. No gaps remain for an agent to misuse 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?

All 9 parameters are documented in the schema (100% coverage). The description adds significant meaning beyond the schema, such as explaining 'Edge is evaluated NET of slippage' for min_edge_pp, operational guidance for slippage_pp, and the purpose of min_partition_leg_kelly in the context of partition arbs.

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 pair ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and clearly states the tool's purpose for agents seeking daily betting opportunities. It distinguishes itself from sibling tools by focusing on Pipeworx data disagreements and structured response segments.

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 positions the tool for 'what should I bet on today' scenarios and mentions tradeable-edge knobs and filters. It implies when to use (discovery) but does not explicitly contrast with siblings or state when not to use it. The context is clear but could include direct alternatives.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, etc. The description adds significant behavioral context: response structure, meaning of fields (e.g., sign of edge_pp_net), limitations (60-day TTL), and data granularity (daily closes). No contradictions.

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

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

Description is front-loaded with a clear summary and evolves logically: purpose, args, response, limits. It is somewhat verbose but each sentence adds value. Slightly more conciseness would be ideal.

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

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

Given no output schema and two optional params, the description is extremely thorough: it explains the three response arrays, their fields, interpretations, and limitations. An agent has all needed information to use 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%, so baseline is 3. Description repeats param info but adds minor context (e.g., 'max 30' vs schema's 'clamp 2-30'). It does not add substantial meaning beyond schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses specific verbs and nouns, and distinguishes itself from siblings like polymarket_edges by focusing on tracking over time.

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

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

The description answers the explicit question 'how long has this edge existed and is it shrinking?' and provides context about when the tool is valuable (e.g., distinguishing fresh vs. old edges). It does not explicitly state when not to use or mention alternatives, but the guidance is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant operational detail: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and warns about forced directional risk. This fully discloses behavior beyond what annotations provide, with no contradictions.

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

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

The description is dense but well-structured: a lead sentence followed by capitalized subheadings for modes. Every sentence adds unique information, and there is no redundancy. It is as concise as possible given the complexity of the tool, though it could be slightly tighter by removing a few parenthetical clarifications.

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

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

Despite lacking an output schema, the description fully enumerates return values for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdicts, etc.) and explains the risk of partial fills and directional exposure. It covers all necessary details for correct invocation and interpretation, making it complete.

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

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

Schema description coverage is 100%, but the description adds value by explaining parameter semantics in context: e.g., size_usd for buys vs. sells, side defaults and auto-detection in basket mode, and the meaning of size_usd as 'settlement notional' for baskets. While the schema covers syntax, the description clarifies usage scenarios, earning a score above baseline 3.

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

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

The description opens with a clear one-liner defining the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It then explicitly distinguishes two modes (single-market and basket) and ties the tool to specific prior actions ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal'), making it easy to differentiate from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use the tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and what not to do ('theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'). It provides clear context and exclusions, 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?

Beyond the read-only/idempotent annotations, the description reveals the response shape, safety fields, compatibility codes, the rule that unclassified legs are never paired, and skipped-comparison counters—exactly the behavioral context an agent needs. Nothing in the description conflicts 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 long but every sentence carries operational meaning: definition, modes, response fields, safety codes, and a final caveat. It is front-loaded with the core purpose and uses field names and code lists to keep the detail navigable.

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 present, the description carries the full burden of explaining return values, and it does so in depth: leg prices, top_spreads_pp, compatibility fields, temporal alignment, and skip counters. For a complex cross-venue tool with three optional parameters, this is complete enough for an agent to call it and interpret results.

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

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

The input schema already documents all three parameters, so the baseline is 3; the description adds value by explaining how topic relates to the explicit ticker/slug mode and that explicit values override the topic-mapped side. It also ties the topic list to its semantics as pre-mapped macro shortcuts.

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 resource—a cross-venue spread between Kalshi and Polymarket for the same resolving question—and explains the two modes, so an agent knows what this tool is for. It doesn't explicitly contrast it with siblings like polymarket_arbitrage or polymarket_edges, so it stops short of full sibling differentiation.

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 concrete mode-selection guidance: use topic shortcuts for pre-mapped macro events and explicit ticker/slug pairings for custom ones, and it warns that pre-mapped topics often produce compatibility warnings and are not automatically tradeable. It doesn't name alternative tools or state when to use those instead, but within the tool the when/when-not guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about scoping ('scoped to your identifier') and pairing, which goes beyond annotations.

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

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

The description is three concise sentences, each serving a purpose: action, usage example, and scoping/pairing. No redundancy.

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

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

Given one optional parameter, comprehensive annotations, and sibling context, the description fully covers behavior, scoping, and relationships. No missing 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 has 100% description coverage for the single parameter 'key'. The description adds meaning by explaining that omitting the key lists all keys, which complements the schema.

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

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

The description clearly identifies the verb ('retrieve' or 'list') and the resource ('value previously saved via remember' or 'all saved keys'). It distinguishes this tool from siblings 'remember' and 'forget' by pairing them.

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

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

The description explicitly says when to use the tool ('to look up context the agent stored earlier') and mentions pairing with 'remember' and 'forget'. It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail: it explains that each event includes source, citation_uri, and raw payload; it describes the mark_read parameter's effect on future calls; and it confirms polling is appropriate. There is no contradiction with annotations.

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

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

The description is a single paragraph with no fluff. Every sentence adds value: purpose, return items, filtering options, mark_read behavior, alternative endpoint. It is front-loaded with the core action and efficiently covers all important aspects.

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

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

Given there is no output schema, the description adequately details what each returned event contains (source, citation_uri, raw payload). It covers optional parameters and their effects. However, it does not explicitly mention ordering (presumably most recent first) or behavior when limit is reached. Still, it is complete enough for a read tool with five optional params, rating a 4.

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%, providing a baseline of 3. The description adds value by giving a concrete example for the type parameter ('sec_8k') and explaining the effect of mark_read on future calls. It also clarifies that since is an ISO timestamp. This goes beyond the schema's simple field descriptions, earning a 4.

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

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

The description clearly states the verb 'Pull' and resource 'fired events from your subscription feed', distinguishing it from sibling tools like list_subscriptions (which lists subscriptions) and subscribe (which manages subscriptions). It specifies the return content (source, citation_uri, raw event payload) and filtering options, 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 provides context on usage: it mentions polling suitability and offers an alternative GET endpoint for scripts/dashboards. However, it lacks explicit when-not-to-use guidance compared to other retrieval tools like search_articles, but the context is sufficient given sibling tool names.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details internal behavior: fans out to multiple sources (SEC, GDELT→GNews fallback, USPTO), soft-fail scenarios, and return format with citation URIs. No contradiction with annotations.

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

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

The description is somewhat lengthy but front-loaded with example queries. Every sentence adds value, though it could be more structured (e.g., bullet points for fallback behavior). No wasted words.

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

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

Given 3 required parameters, full schema coverage, and no output schema, the description explains return structure (grouped changes, total count, citations) and handles edge cases like USPTO soft-fail. Slight miss on pagination or error handling, but adequate 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 already has 100% coverage, but the description adds practical meaning: explains ISO vs relative shorthand for 'since', recommends defaults ('30d'), clarifies ticker/CIK for 'value', and notes only 'company' for 'type'. This goes beyond basic schema.

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

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

The description clearly states the tool provides a 'change feed for a company' with specific verbs like 'What's new with X' and lists example queries. It distinguishes from the sibling 'entity_profile' by noting the latter is for static profiles.

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

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

The description explicitly tells when to use this tool (for recent changes/news/patents) and directs users to 'entity_profile' instead for static profiles. However, it lacks explicit exclusion scenarios or when-not-to-use guidance.

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

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

Annotations indicate idempotent and non-destructive write. Description adds retention details (persistent vs 24-hour), scoping by identifier, and pairing with other tools, going beyond annotation hints.

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

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

Three well-structured sentences front-load purpose, then usage guidance, then behavioral details. Every sentence adds unique value without redundancy.

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

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

Given no output schema needed for a write tool, the description adequately covers persistence, scoping, and integration with recall/forget. Could mention overwrite behavior (idempotent) explicitly.

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

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

Schema already provides parameter descriptions with examples (key naming). Description reinforces usage and suggests conventions, adding value despite 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 description clearly states the tool saves data for reuse later, specifies the verb 'save' and resource 'data', and distinguishes from siblings like recall and forget by describing its storage role.

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

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

Provides explicit guidance on when to use (discover something worth carrying forward) with examples, and mentions pairing with recall/forget. Lacks explicit 'when not to use' but context is clear.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description details internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, source labeling, and explicit handling of unresolved identifiers. This is rich behavioral context that annotations alone do not provide.

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

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

The description is dense but well-organized, starting with user-phrased examples, then the core purpose, followed by type-specific details. Every sentence adds meaningful information, though the initial example list is somewhat long. It could be slightly trimmed without losing value.

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

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

There is no output schema, so the description carries the responsibility of explaining return values. It explicitly states what is returned for companies (CIK, ticker, company_name, LEI, FIGI, with source labels and an unresolved section) and for drugs (RxCUI, ingredient, brand, citation). It also covers error/degradation behavior, making it complete for effective invocation.

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

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

The input schema already provides full descriptions for both parameters (type and value), including enums and examples. The description adds nuanced context like ISIN-to-LEI mapping and drug brand/generic scope, but since schema coverage is 100%, 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 the tool's function: resolving user-spoken names to canonical identifiers. It provides concrete examples of queries and explicitly contrasts with tools requiring IDs as input, distinguishing it from siblings like 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?

The description gives explicit usage guidance: "Use FIRST whenever you have a name but need an ID." It also clarifies supported entity types and inputs. However, it does not explicitly mention when NOT to use this tool or name alternative tools for related tasks, so it stops short of full when/when-not coverage.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it probes entities with ai_visibility_check and returns ranked list with score, confidence, signal density. No contradiction. Extra context on API key requirement for anthropic model.

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

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

Two sentences with no waste. Front-loaded with purpose, followed by method and example. Every sentence adds valuable context.

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

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

Despite no output schema, description clearly states return format (ranked list with score, confidence, signal density). All 4 parameters are explained in schema, and description ties them together. Enough for an agent to understand usage and output.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that the first entity in the array is treated as the 'subject' for narrative, which is not in the schema. Also implies 'models' array behavior with optional _apiKey.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side and ranks them, distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (generic). Action verb 'compare' and resource 'AI visibility' are explicit.

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

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

Description provides a clear use case (competitive AI-marketing audits) and an example query. It implicitly suggests when to use but does not explicitly state when not to use or name alternatives like ai_visibility_check for single entity checks.

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

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

Discloses graceful degradation for bundlephobia timeouts (5-30s) and the sources_failed field, which adds value beyond the safe-read annotations. 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?

Efficiently structured: purpose first, then usage, then detailed behavior and return. Every sentence is informative with no fluff.

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

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

Thoroughly covers return structure (summary block, advisories, links, alternative versions) and behavior (partial failures, timing). No output schema, so description compensates fully.

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

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

Schema coverage is 100%, but description adds context: scoped packages are accepted, version defaults to latest. This adds some value beyond schema descriptions, but schema already does significant work.

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

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

The description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia data. It explicitly mentions evaluating safety, popularity, and size, distinguishing it from sibling tools like resolve_entity.

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

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

Provides explicit usage: 'Use whenever an agent asks "is X safe / popular / small"'. Also specifies ecosystem limitations and directs to alternatives for other ecosystems, offering clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by stating 'Newest first' ordering and 'Keyless' access, complementing the annotations without contradiction.

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

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

Single sentence efficiently conveys the main functionality, sources, and filtering options. Could be slightly more structured (e.g., bullet points) but remains clear and 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?

The description covers search scope, sources, and filters but omits details on return format, pagination, or default behavior beyond 'newest first'. Given no output schema, additional context would improve 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 parameters have descriptions in the input schema (100% coverage). The tool description provides overarching context but adds no new semantic information beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it performs full-text search over spaceflight news articles from multiple specific sources, with filtering options. It distinguishes itself from siblings like 'get_article' (single article retrieval) and 'list_sources' (source listing).

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 for searching articles with filtering, but lacks explicit guidance on when to use this tool versus siblings or alternatives. It mentions 'Keyless' indicating no auth needed, but no direct comparisons.

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

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

Discloses behavioral details beyond annotations: truncation at 200K chars with flagging, embedding model (BGE-base-en), overlapping 500-char windows, and that passages include offsets and similarity scores. Annotations already declare readOnlyHint and idempotentHint, so description adds value.

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 main purpose, and every sentence adds meaningful detail. No redundancy or fluff.

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

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

Given the absence of an output schema, the description covers return format (top-N passages with offsets and scores), limitations (200K char cap), and pairing with other tools. Complete for an agent to use 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%, so baseline is 3. The description adds examples for the query parameter and clarifies truncation for text, but the schema already provides good descriptions. Minor added value beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' identifying the action and resource. It distinguishes from siblings by mentioning 'Pairs with ask_pipeworx_grounded' and the use case of searching within a record instead of the whole document.

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

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

Explicit guidance: 'Use when the record is too big to cram into the prompt.' Also notes when not to use it (when the record fits) and suggests alternative pairing with ask_pipeworx_grounded.

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

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

Annotations indicate this is a write operation (readOnlyHint=false) and idempotent. Description adds: requires OAuth, returns subscription id, delivery channels with always-on feed, optional email/sms/webhook with specific constraints (sms phone verification, 10/day cap, webhook HMAC signing and auto-disable after failures). No contradictions with annotations.

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

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

Single paragraph but dense with information, front-loading core purpose. Could benefit from bullet points for readability, but not verbose given 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?

Covers all aspects: prerequisites, type-specific params, delivery options with constraints, return value (subscription id). No output schema but description states return. Includes limitations (sms cap, webhook auto-disable). Complete for a subscription creation tool with complex parameters.

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

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

Schema coverage is 100%. Description enriches every parameter: type enum with examples and item codes; params with type-specific structures and defaults; delivery with details on email, sms (verification, cap), webhook (signing, auto-disable). Adds significant value beyond schema.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' Distinguishes from siblings like list_subscriptions and unsubscribe by specifying it creates a new subscription. Includes supported types for further differentiation.

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 requirement for Pipeworx OAuth account and that anonymous/BYO cannot persist. Provides context on when to use (proactive monitoring) and covers supported types with examples. Lacks explicit when-not-to-use but context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return structure (category-bucketed example questions with exact tool + argument shape) and noting it draws from a live catalog of thousands of tools. No contradictions.

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

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

The description is relatively long but front-loaded with common query examples. Every sentence adds value, though some verbosity could be trimmed. The structure is logical, moving from example queries to function output to usage instructions.

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

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

Given the lack of output schema, the description adequately explains the return format (category-bucketed examples with exact tool calls and arguments). It also mentions the live catalog and optional topic filtering. Sufficient for an onboarding tool.

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

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

Input schema covers 100% of the single parameter 'topic' with a description listing possible values. The description elaborates by giving concrete examples (e.g., 'finance', 'pharma', 'betting') and explaining the effect of omitting the parameter. This adds meaningful guidance beyond the schema.

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

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

The description clearly identifies the tool as the onboarding entry point for an agent that just connected, returning category-bucketed example questions with exact tool calls. It distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by stating it is meant to be used first when the agent does not know what Pipeworx can do.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear context for when to invoke. It also mentions optional topic parameter for focus. No explicit when-not-to-use, but the context implies it is not needed once familiar with available tools.

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

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

Adds key behavioral details beyond annotations: deactivation (not deletion), ownership enforcement, and historical data preservation via recent_alerts, aligning with destructiveHint=false and idempotentHint=true.

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

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

Two concise sentences with no fluff, front-loaded with the action verb. Every word is meaningful.

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 one simple parameter, no output schema, and clear annotations, the description fully explains purpose, side effects, and ownership, leaving no gaps.

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

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

Schema coverage is 100% and the description adds minimal new meaning beyond 'by id', which is already in the schema's description.

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

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

The description uses a specific verb ('cancel') and resource ('subscription by id'), clearly distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

States when to use (cancel subscription) and notes ownership enforcement, but no explicit when-not or alternative tools, though context is clear from sibling list.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds crucial behavior: the fast-path vs grounded pipeline routing, the meaning of each verdict, and the critical warning that 'could_not_verify' means the check did not happen and must not be presented as evidence. This goes well beyond annotation defaults.

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: trigger phrases, when-to-use, routing behavior, return verdicts, and the important caller caution are all tightly packed. It is front-loaded with examples, uses a clear structure, and avoids 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?

Given the tool's complexity (two distinct verification pipelines, multiple verdicts, error semantics), the description covers what returns, how to interpret each verdict, and the crucial distinction between could_not_verify and unsupported. No output schema exists, so this text fully carries the completion burden and succeeds.

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

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

Despite 100% schema coverage, the description adds substantial parameter behavior: tolerance_pct overrides the claim-implied tolerance, with concrete guidance (1–2% for hallucination detection) and the default cap of 5%. The claim parameter is illustrated with realistic examples. This transforms dry schema into actionable 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 uses a specific verb+resource: 'natural-language claim verification against authoritative sources' and includes many trigger phrases like 'fact check', 'verify the claim that…', 'true or false'. It clearly distinguishes itself from sibling tools by stating it replaces a 4–6 step pipeline and handles both company-financial and other factual claims.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also spells out the alternative of making 4–6 sequential calls, and clarifies that non-financial claims automatically fall through to the grounded pipeline, leaving no ambiguity about coverage.

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