Nasa Eonet

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, indicating safe, non-destructive behavior. The description adds value by detailing the scoring range (0-100), the default free model, the BYO key requirement for Anthropic, and the per-model return structure (score, confidence, signals, raw_response). 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 four sentences with no wasted words. The first sentence immediately states the core function and return format. Subsequent sentences add important details (default model, API key usage, use cases) efficiently.

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

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

Given no output schema, the description adequately explains the return structure (per-model score, confidence, signals, raw_response + combined view). It also lists specific use cases and mentions cost implications for Anthropic. The description is complete for this 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 description coverage is 100%, so baseline is 3. The description adds context beyond the schema: it specifies that 'models' can be omitted for just workers-ai, explains that '_apiKey' is passed directly to Anthropic and not stored, and notes that 'context' helps disambiguate. This enhances parameter understanding.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the default model, optional Anthropic integration, and return structure. It also lists specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), which distinguishes it from sibling tools like deep_research or scan_competitor_ai_presence.

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 for when to use the tool (e.g., brand visibility audits, competitive monitoring). It does not explicitly state when not to use it or list alternatives, but the use case specificity gives sufficient guidance for an AI agent.

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

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

Annotations already carry readOnlyHint and idempotentHint, so the bar is lower. The description aligns (it returns structured answers, never mutates) and adds genuinely useful behavior: it auto-routes to one of 5,581 tools across 1,463 sources, fills arguments itself, and returns 'stable pipeworx://' citations. These are the kind of expectations an agent can't infer from the schema. It only loses a point for not stating error/edge behavior (e.g. what happens when no source matches).

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

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

The description is long, but every sentence is load-bearing: the block-cap imperative, the domain list, the alternatives, the examples, and the step-up guidance. It is front-loaded ('PREFER OVER WEB SEARCH…') and the examples are concrete. It is arguably over-engineered (the domain list is 14 items and the examples overlap with the domain list), so not a 5, but nothing is wasted.

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

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

For a general-purpose auto-routing query tool with only one required parameterable and rich sibling tools, the description covers all bases: trigger conditions, precedence over web search, escalation path to grounded/deep variants, routing scope, and output citation format. The input schema plus examples fully cover parameter usage. Nothing an agent needs is missing.

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

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

Schema coverage is 100%: the required 'question' parameter and all five aliases (q, text, input, prompt) are documented in the schema itself, and the alias descriptions are clear enough that an agent can pick any synonym. The description is nearly silent on parameters (it never mentions the aliases or that any string works), so it adds nothing beyond the schema — but it doesn't need to. Per rubric, high coverage baseline is 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 by naming the tool's role ('PREFER OVER WEB SEARCH for questions about...') and enumerates dozens of concrete data domains (SEC filings, FDA drug data, BLS statistics, patents, weather…). It explicitly contrasts itself with siblings ask_pipeworx_grounded and deep_research, and gives a specific routing rule ('START HERE…'), so an agent can instantly tell this from its siblings without inspecting 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?

The description gives an explicit decision rule ('PREFER OVER WEB SEARCH… START HERE…'), names exact alternatives with the condition that selects them ('for a hallucination-resistant single answer use ask_pipeworx_grounded; for fan-out use deep_research'), and supplies six concrete example queries so the trigger conditions are unambiguous.

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

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

The description discloses that it is an experimental edge with candidate routing improvements, and clarifies that currently no candidate is active, so it matches ask_pipeworx exactly. It also states it is a full working router with no fallback. This goes beyond the annotations (readOnlyHint, idempotentHint, etc.) by explaining the experimental aspect and the current equivalence to the stable version, adding valuable 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 a single paragraph that front-loads the key fact ('Beta version of ask_pipeworx') but then includes details like the retirement date (2026-07-26) and the phrase 'candidate routing improvements enabled live whenever one is under test', which add verbosity without aiding agent decision. It is longer than necessary but still organized around the main points.

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 large scope (universal router with 5,581 tools), the description provides enough context by referring to ask_pipeworx and explaining the current behavior. It does not include examples, response format, or specific usage scenarios, but the reference to ask_pipeworx and the explicit 'use exactly like' guidance covers the essentials for an agent familiar with the stable version. It is adequate but not exhaustive.

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

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

The schema covers all parameters (question and aliases) with descriptions, achieving 100% coverage. The description only says 'same arguments' without adding new semantics. With full schema coverage, a baseline of 3 is appropriate; the description does not need to compensate for missing information.

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 it is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. This clearly defines its function as a routing tool for questions, and distinguishes it from the stable ask_pipeworx by its beta status. However, it lacks a specific verb-resource phrasing like 'route a question', relying instead on the name and comparison.

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

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

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router, implying when this tool is preferred. It does not explicitly state when not to use it, but the context of 'newest routing' and comparisons to the stable router provides adequate direction.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds substantial behavioral detail beyond annotations: refusal reasons, exact return shape, verbatim evidence, refusal conditions, and the extra LLM call cost. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return contract, refusal contract, usage guidance, and cost tradeoff. Front-loaded with the key differentiator before details.

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

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

Despite having no output schema, the description provides a complete return contract including refusal_reason enum values. Input schema is simple and fully covered. The usage context, alternatives, cost, and safety considerations are all addressed.

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% and the schema fully documents each alias for the single question parameter. The description does not add parameter-specific meaning, but none is needed since the schema already carries the semantic weight.

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 a specific mode: a hallucination-resistant answer extraction tool for high-stakes reads. It differentiates itself from the sibling ask_pipeworx by stating it uses only the tool result content and returns explicit refusals when data cannot answer.

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: whenever an answer will be quoted, cited, or acted on and must not invent facts. Also names the alternative ask_pipeworx and advises preferring it for casual lookups, including the cost tradeoff.

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

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

The description extensively details behaviors beyond annotations: fan-out logic, category classifiers, response shapes, resolver contract, parent event extraction, news fallback handling, safety limits, and resolution-rule risk. No contradiction with annotations.

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

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

The description is lengthy but well-structured with capitalized sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and a front-loaded summary. Every sentence adds value, though it could be slightly more concise.

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

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

Given the complexity and lack of output schema, the description covers all necessary aspects: input formats, internal processing, output structure, edge cases (closed markets, low confidence), and explicit warnings (resolution-rule risk). Completely adequate for correct tool usage.

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 meaningful context: explains market parameter can be slug, URL, or question text; depth and include_raw parameters are elaborated with usage scenarios and examples.

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

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

The description uses specific verbs and resources: 'Research a Polymarket bet by pulling the relevant Pipeworx data'. It clearly distinguishes from siblings like polymarket_edges or polymarket_arbitrage by focusing on comprehensive bet research including evidence and market comparison.

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

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

Explicit usage contexts are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' No explicit when-not-to-use or alternatives, but the description thoroughly explains the tool's scope.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: correct handling of off-calendar fiscal years (e.g., AAPL Sep, NVDA Jan), specific data sources (SEC EDGAR/XBRL, FAERS), and return format (paired data + citation URIs). No contradictions with annotations.

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

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

The description is a single dense paragraph but front-loads the most critical usage examples. Every sentence adds value, though a slightly more structured format (e.g., separating examples, data sources, sorting) could improve scannability. It is appropriately concise for the information density.

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 conveys what is returned: paired data and pipeworx:// citation URIs per entity. It also mentions sorting behavior. For a comparison tool that replaces 8-15 sequential lookups, this is sufficiently complete to guide the agent on expected results.

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

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

Schema coverage is 100%, and the description enriches both parameters: 'type' is explained as 'company' or 'drug' with clear data implications, and 'values' is described with examples (tickers/CIKs for company, drug names for drug) and constraints (2-5 items). This adds meaningful semantics beyond the schema's minimal descriptions.

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

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

The description opens with colloquial query examples that directly convey the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It explicitly states what financial data is pulled for companies (revenue, net income, cash, long-term debt from SEC EDGAR/XBRL) and what drug data is pulled (FAERS adverse events, FDA approvals, active trials). This distinguishes it from sibling tools like entity_profile or single lookups.

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

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

The description clearly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a strong usage recommendation. It also explains that results are sorted by primary metric to answer queries like 'largest' or 'biggest'. While it doesn't explicitly list when not to use, the alternative strategy is well-addressed.

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

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

With no annotations provided, the description itself carries the behavioral contract. It specifies inputs, processing ('routes to one of 5,581 tools'), the output shape (findings with evidence/confidence/source, gaps[]), and even notes that gaps[] are never invented; 'standard' vs 'thorough' depth behavior is detailed. This is unusually rich behavioral context.

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

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

The description is long (~200 words) but every sentence adds distinct value: capability, restriction, account requirement, fallback, output format, nuance about depth, gap behavior, and sibling alternatives. It is not bloated; each clause communicates a separate operational fact. A 5 would require tighter organization with headers or bullet points, but it remains efficient prose.

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?

An agent has everything needed to decide to call it: account requirements, authentication URL, pricing fallback, parameter effects, output contract, and explicit unsupported-case routing. The description also anticipates failure (empty gaps[]) and provides a fallback. I see no missing context that would cause a mis-call.

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

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

Both parameters are fully explained. The schema gives only enum constraints for 'depth', but the description adds semantics: 'quick=single hop', 'thorough adds iteration and contradiction scan', and explains that deeper hops cost more credits. 'question' is implied as free-form but the description also lists the kind of questions it handles well vs poorly. Since schema coverage is 100% and the description enhances both parameters beyond the enum, this is a 5.

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 exactly what the tool does: 'multi-source research across Pipeworx's 1,463 structured data sources' with a concrete decomposition strategy ('decomposes your question into focused facets') and specifies what it returns (verbatim evidence + confidence + citation). It also distinguishes itself from free-form search by noting 'this is NOT open-web search', so an agent knows its scope precisely.

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 an agent WHEN to use this tool (broad/multi-part questions over structured data) and when NOT to: for single lookups it says 'use ask_pipeworx', and for breaking/current news it says 'prefer ask_pipeworx because it routes to news APIs'. This is exactly the kind of call-routing guidance an agent needs, far beyond generic 'use for research'.

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 behavioral context about the output: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This goes beyond annotations to explain what the tool actually does.

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 dense paragraph that front-loads the purpose and lists relevant domains. It is informative but could be slightly more concise; still, every sentence contributes value.

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

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

Given no output schema, the description adequately explains the return format (tools with names, descriptions, schemas). It covers all parameters. However, it doesn't mention ranking criteria or potential limitations, which would make it more 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%, so baseline is 3. However, the description adds significant value by explaining the query parameter with natural language examples and listing all aliases. It also clarifies the limit parameter's default and max. This provides richer semantics than the schema alone.

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

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

The description clearly states it finds tools by describing data or task, listing many domains. It distinguishes itself from sibling search tools by positioning as a meta-tool for exploration, explicitly saying 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description explicitly says when to use it: 'when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST... want to see the option set (not just one answer).' It lacks explicit when-not-to-use or alternative tool guidance, 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?

Beyond annotations (readOnlyHint, etc.), the description details the fan-out across multiple sources, specific return fields with formats (e.g., recent_filings URIs, fundamentals sorted by period_end DESC), and patent soft-fail behavior. 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 efficient, starting with intuitive examples followed by core purpose and detailed breakdown. It is slightly lengthy but every sentence adds value, earning a high score.

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

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

Given no output schema, the description thoroughly explains returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with sources and limitations. It is complete for understanding the tool's 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%, but the description adds context: type only 'company' with future plans, value requires ticker/CIK with examples and explicit note that names are not supported, directing to resolve_entity.

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

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

The description explicitly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with example queries. It clearly distinguishes from siblings like resolve_entity (name resolution) and compare_entities (comparison).

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

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

The description instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and explicitly states when to use resolve_entity for name resolution. It also notes patent sunset limitations.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context about the specific return fields (event id, title, category, dated geometry, links) and the filtering dimensions, enhancing transparency beyond the annotations without contradicting them.

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

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

The description is compact at two sentences, first identifying the data source and categories, second covering filters, returns, and intended use. It is efficient but the second sentence is dense and could be split for easier scanning.

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 rich output schema and annotations, the description fully orients the user by naming the data source, categories, filter types, return fields, and the question it answers. No critical context is missing.

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

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

The input schema covers all 9 parameters with descriptions, so the baseline is 3. The description merely re-lists filter types (status, days, category, bbox, source, magnitude) without adding new meaning, as the schema already provides details like the non-standard bbox order.

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 resource (NASA EONET natural hazard events), the action (filter and retrieve events), and the output (event id, title, category, geometry, links). It distinguishes from siblings like get_event by emphasizing the filtering and listing capability.

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

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

Provides a clear use case: find active or recent natural hazard events by various filters. It does not explicitly name alternative tools or exclusions, but the context is unambiguous enough to know when to use this tool.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about why to use it (stale, done, sensitive) and confirms deletion. No contradictions.

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

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

Three concise sentences: action, usage, pairing. No unnecessary words, front-loaded with purpose.

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

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

With one parameter and annotations covering safety, the description is sufficient. It doesn't explain return values (no output schema) or errors, but for a simple delete tool it's complete enough.

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

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

Schema coverage is 100% with a clear description for the key parameter. The tool description reinforces that it deletes by key and explains the context of memory deletion, adding value beyond the schema.

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

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

The description clearly states the tool deletes a memory by key, using the specific verb 'delete' and resource 'memory'. It distinguishes itself from siblings by naming 'remember' and 'recall'.

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

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

The description provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and pairs with remember and recall. It lacks explicit when-not-to-use 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?

Adds behavioral context beyond annotations: 'Fetches the page, extracts title/description/key links, and emits markdown format.' This aligns with readOnlyHint and describes the process. Could mention error handling or rate limits.

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 plus a bulleted list. Front-loaded with purpose, no redundant information, and every sentence adds value.

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

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

Given full schema coverage, good annotations, and no output schema, the description explains the return format ('single text blob'). Could explicitly mention markdown output, but the context is sufficient.

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

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

Schema coverage is 100% and both parameters have descriptions. The description repeats the schema info without adding new semantics. 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 verb 'generate', the resource 'llms.txt file', and scope 'for any URL'. It distinguishes itself from sibling tools like 'ai_visibility_check' by specifying a unique output format and purpose.

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

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

Provides three specific use cases (client indexing, own project drafting, competitor auditing), giving clear context for when to use. Lacks explicit when-not-to-use or alternative tool names, but the use cases are 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=false. The description adds only the return format (GeoJSON FeatureCollection) but does not disclose any behavioral traits beyond what annotations provide. It fails to add significant behavioral context.

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

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

The description is a single sentence that immediately states the relationship to 'events' and the key differentiator (GeoJSON output). No redundant information; every word 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 5 undocumented parameters and no clarification of what 'events' entails, the description is incomplete. While the output schema exists, it does not explain input constraints or behavior. The tool relies heavily on external 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 5 parameters with 0% description coverage, and the tool description provides no information about any parameter. Since schema coverage is low, the description must compensate, but it does not. Users cannot determine how to use parameters without external knowledge (e.g., from the 'events' tool).

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 indicates the tool returns GeoJSON FeatureCollections, distinguishing it from the sibling 'events' tool. It specifies the output format and use case for map rendering, making the purpose clear. However, it relies on knowledge of what 'events' does.

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 the tool is 'good for direct map rendering', providing a clear use case. Comparing to 'events' implies that raw events data should be used otherwise. No exclusions or when-not-to-use guidance is given, but the 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, etc. Description adds no further behavioral traits 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?

Extremely concise (8 words), front-loaded with verb and resource, no wasted text.

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?

Complete for a simple fetch-by-id operation with full schema, comprehensive annotations, and an output schema (not shown but present).

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

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

Schema coverage is 100%; description reinforces the parameter's purpose but adds no new semantics beyond the schema.

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

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

Clearly states the action (Fetch), resource (single event), and identifier (EONET id). Distinguishes from sibling 'events' likely used for 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?

Provides clear context to fetch a specific event, but lacks explicit exclusion criteria or mention of alternatives like 'events' for listing.

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 clearly indicate read-only, idempotent, non-destructive behavior. Description adds value by specifying the returned fields (id, title, description, layers) and their role in filtering, 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, no wasted words. Directly conveys purpose and content. Well-structured for quick comprehension.

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 parameters, an output schema present, and comprehensive annotations, the description provides all necessary context. It explains what the data is used for and the fields contained.

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?

No parameters exist, so schema coverage is 100%. Baseline score for zero parameters is 4; description correctly lists the output fields, which is sufficient.

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 returns EONET event category definitions with specific fields (id, title, description, layers). It distinguishes from siblings like events and geojson by specifying categories as a filtering resource.

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

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

Usage context is implied ('used to filter the events and geojson tools') but no explicit when-to-use or when-not-to-use guidance is provided. The tool's simplicity mitigates the need, but a description of its role relative to other tools would help.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety. The description adds the concept of 'mapping events to imagery layers' but does not disclose pagination, filtering behavior, or response format beyond the schema.

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 sentence—short and to the point. It is front-loaded and avoids wasted words, though it could be more informative.

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

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

Despite having an output schema and clear annotations, the description lacks detail on what the tool returns (e.g., layer names, IDs, mapping logic). It is incomplete for an AI agent to fully understand the tool's purpose 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% with the 'category' parameter already described. The description does not add any extra meaning or examples for the parameter, so baseline score 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 'Visualization layer reference (mapping the events to imagery layers)' indicates the tool provides layers for visualizing events, but it uses a noun ('reference') instead of a clear verb+resource structure. It distinguishes from siblings like 'events' or 'list_categories' but not explicitly.

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?

No guidance is provided on when to use this tool vs alternatives. Sibling tools exist (e.g., 'list_categories', 'events') but the description does not mention context or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful context: it returns specific fields (id, title, homepage URL) and clarifies that sources are 'official' from EONET. No contradictions with annotations.

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

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

The description is concise—one sentence that conveys the purpose, resource, and output structure. It is front-loaded with the verb and resource, making it easy to parse quickly.

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 zero parameters, an output schema exists, and the description explains what is returned and why, the description is fully complete for its simplicity. No additional information is needed.

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, so schema coverage is 100%. The description adds no parameter-specific information, which is acceptable as there are no parameters to describe.

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 'Return', the resource 'all official data sources', and specifies the fields returned (id, title, homepage URL) along with the context of EONET aggregating natural-event records. It distinctly sets the tool apart from its siblings, as no other tool appears to list sources.

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

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

The description implies usage for fetching a list of sources, but does not explicitly state when to use this tool over alternatives or provide any exclusion criteria. However, given the tool's simplicity and lack of similar siblings, the intended use 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and usage context, no contradictions.

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

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

Two short sentences, no redundant information. Efficiently conveys purpose, return data, and usage 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?

Simple tool with one optional parameter and no output schema; description lists return fields and usage. Completely addresses what an agent needs.

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?

Only one parameter, fully described in schema. Description adds no additional meaning beyond the schema, 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?

Clearly states 'List the caller's active subscriptions', providing a specific verb and resource. Differentiates from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says to use 'to review what you're monitoring before adding more or to find an id to cancel', giving clear context. Lacks explicit when-not-to-use, but adequate.

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

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

With all annotations false, the description carries the full burden and does an excellent job. It discloses the claim_token return/read behavior, rate limit (5 per day), cost (free), and that it doesn't count against tool-call quota. It also explains feedback digestion and roadmap impact, giving a complete picture of the tool's side effects.

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

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

The description is longer than average but every sentence earns its place: purpose, usage cases, exclusions, token mechanics, rate limits, and framing rules. It is front-loaded with the core purpose and structured logically. A perfect 5 would require slightly tighter wording, but this is high-quality density.

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 feedback tool with no output schema, the description covers all necessary context: when to use, how to use, what happens as a result, and operational constraints. It even addresses edge cases like anonymous filing via claim_token and cross-server confusion. No significant gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant value beyond the schema. It explains how to use claim_token with an example, clarifies the context parameter semantics, and provides usage guidance for message framing that the schema lacks. This lifts it above the baseline, though not to 5 because the schema already documents each parameter well.

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 ('tell') and resource ('the Pipeworx team') with clear scope: reporting bugs, features, data gaps, or praise. It also distinguishes from siblings by specifying it is only for tools served by this Pipeworx connection, not for tools from other MCP servers.

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

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

The description explicitly lists when to use the tool (bug, feature/data_gap, praise), provides an exclusion (other MCP servers' tools), and gives clear guidance on how to frame feedback (in terms of Pipeworx tools/packs, not user prompts). This exceeds the bar by covering both included and excluded scenarios.

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

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

Discloses caching (5min-1h), self-aggregating nature, no PII, and data source (CF analytics-engine), adding value beyond annotations that only state it is read-only and idempotent.

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 plus bullet points, no waste. Front-loaded with purpose, then uses, then technical details.

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

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

With no output schema, the description explains return fields (top tools, packs, volume) and caching. All necessary context for agent selection is present.

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

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

The single parameter 'window' is fully described in schema (enum with descriptions). The description adds behavioral nuance: shorter windows for current hotness, longer for steady-state demand.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over specific windows. It distinguishes itself from siblings like discover_tools and ask_pipeworx by focusing on trending metrics derived from agent activity.

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 three concrete use cases (hot data sources, canonical tool confirmation, use case alignment) but does not explicitly mention when to avoid or compare to alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral context: the monotonicity checks, partition_sum logic, semantic anchor (Jaccard similarity ≥0.30), placeholder filter, and fill check (realizable_edge_pp ≤0 means no trade). No contradictions with annotations.

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

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

The description is thorough but somewhat lengthy. It uses section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize information, which aids readability. Some details could be more streamlined, but overall it is well-structured and front-loaded with the main use cases.

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

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

Despite no output schema, the description details the response structure including fields like opportunities[], partition_check, and fill_check details. It covers all three invocation modes, explains the semantic anchor and partition filter, and references sibling tool polymarket_fill_risk for custom sizing. The tool's complexity is fully addressed.

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 already describes parameters. The description adds value by explaining behavior for each parameter: no args triggers trending scan, event mode walks child markets and runs partition_check, topic mode searches related events. It also provides examples of valid inputs for both parameters.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and contrasts with sibling tools like polymarket_edges.

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

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

Explicitly instructs when to use each mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also provides recommendations and explains when cross-event mode catches patterns that single-event misses.

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

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

The description extensively details the three response segments, model families, Kelly calculations, slippage, tradeable-edge knobs, caching policy, and diagnostics. Annotations already mark it as readOnlyHint=true and idempotentHint=true, and the description is fully consistent, adding significant behavioral context beyond structured fields.

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 quite long and includes detailed model parameter values (e.g., α for tennis 1.02) that may not be essential for an agent to invoke the tool. While it front-loads purpose, it could be more concise without losing clarity.

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 (9 parameters, no output schema), the description is remarkably complete. It explains the return structure (by_segment, fed_candidates, _diagnostics), caching, and caveats like the fed_note warning. No output schema exists, so the description carries the full burden and delivers.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some extra context for parameters like min_edge_pp ('Edge is evaluated NET of slippage') and min_partition_leg_kelly (explaining why it exists), but overall the schema already explains each parameter sufficiently.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' clearly stating the specific verb and resource. It distinguishes from siblings like polymarket_arbitrage by emphasizing the Pipeworx disagreement angle.

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 states 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets,' providing clear usage context. It does not explicitly compare to alternatives but gives enough guidance for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by explaining that decay is computed from daily closes (not intraday), history bounded by 60-day TTL, and gaps when cache misses occur. 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 main purpose and uses clear sections (ARGS, RESPONSE, LIMITS). It is detailed but each sentence provides essential information. Could be slightly more concise without losing meaning.

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

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

Given no output schema, the description thoroughly explains the response fields (tracked[], expired[], snapshot_dates[]) and their semantics. It also covers limits and edge cases like gaps, making it highly complete for both agent and human.

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 parameters have descriptions. The description adds context on defaults (14 for days, '1wk' for window) and clamping (days 2-30). Baseline is appropriate as the description adds marginal value beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. This specific verb-resource combination distinguishes it from siblings like polymarket_edges.

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

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

The description implicitly tells when to use (for understanding edge longevity and decay) by contrasting fresh vs. old edges. While it doesn't explicitly name alternatives, the context is clear. Could improve by stating 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?

Description adds significant behavior details beyond annotations: walks order book ladder, returns specific metrics (top_of_book, slippage, verdict), basket per-leg details, thin_legs, forced_directional_risk. Annotations already indicate safety, but description enriches understanding.

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

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

Well-structured with clear sections for single-market and basket. While longer than some, every sentence adds necessary context for a complex tool. No waste, but could be slightly condensed.

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 covers all relevant return values and edge cases (thin_legs, max_clean_notional, forced_directional_risk). Leaves no critical gaps for an agent to understand usage.

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

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

Schema coverage is 100%, but description adds meaning: explains side defaults and auto-detection for basket, clarifies size_usd interpretation (settlement notional for basket, spend/proceeds for single). Enhances schema without redundancy.

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 checks realizable vs theoretical edge against live CLOB order-book depth. Differentiates between single-market and basket modes. Explicitly distinguishes from sibling tools by stating usage before polymarket_arbitrage or polymarket_edges trades.

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

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

Provides explicit when-to-use guidance: before acting on arb signals or trades above ~$500. Explains risks of partial fills and thin books, giving strong usage context. Could add when-not-to-use, but the guidance 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is clear. The description adds extensive behavioral context: explains the two modes, response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters), and edge cases (compatibility_warning conditions). No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. It uses clear section headings (TWO MODES, RESPONSE, SAFETY FIELDS). However, it is somewhat verbose; some details could be condensed without losing clarity. Still, 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?

Since there is no output schema, the description fully explains the response fields: venue prices, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It covers edge cases and caveats, making the tool's behavior fully predictable. The level of detail is appropriate 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?

Input schema coverage is 100%, but the description adds significant meaning: explains the 10 pre-mapped topic shortcuts, how explicit tickers override, and the interaction between modes. Examples in the schema further clarify usage. This adds substantial value beyond the schema alone.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by specifying cross-venue functionality. The scope is well-defined with two modes (topic shortcuts and explicit tickers).

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 guidance on when to use each mode (topic vs explicit) and warns that most pre-mapped topics return compatibility warnings, indicating when results may be meaningful. However, it lacks explicit comparison with sibling tools like polymarket_arbitrage, which could help the agent decide between 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=true and idempotentHint=true. Description adds dual behavior (retrieve vs list), scoping details, and relationships with sibling tools, providing 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?

Description is efficient, covering purpose, usage, scoping, and pairing in one paragraph. No wasted sentences, though could be slightly more concise.

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

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

For a simple tool with one optional parameter and no output schema, the description adequately covers retrieval, listing, scoping, and relationships. Lacks error handling or return format details, but is sufficient for agent 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 coverage is 100% with clear parameter description. The description adds the crucial detail that omitting key lists all keys, which is not in the schema but is essential for understanding the parameter's behavior.

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 retrieves a value by key or lists all keys when omitted, using specific verbs 'retrieve' and 'list'. It distinguishes from sibling tools 'remember' and 'forget' by explicitly pairing with 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?

Explicitly states when to use (look up previously stored context) and implies when not (save with remember, delete with forget). Also clarifies scoping to user identifier.

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 transparently discloses the mark_read:true side effect (flags events as read) and mentions what data each event carries. However, there is a contradiction with annotations: readOnlyHint=true is inconsistent with the described mutation. This contradiction is flagged.

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 reasonably concise but could be more structured. It front-loads the purpose and then details parameters and behavior. Every sentence adds value, though the alternative URL mention is slightly tangential.

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

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

Given no output schema, the description adequately describes return values (source, citation_uri, raw payload) and covers all parameters and behaviors. It is complete for a read tool with optional mutation.

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

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

The description adds meaningful context beyond the schema, e.g., 'e.g. "sec_8k"' for type, 'ISO timestamp' for since, and explains the effect of mark_read. Schema coverage is 100% but description still adds value.

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

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

The description clearly states 'Pull fired events from your subscription feed' providing a specific verb and resource. It distinguishes itself from siblings by being focused on alerts/events, which is a distinct functionality among the listed tools.

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

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

The description gives practical usage guidance: filter by type and since, mark_read behavior, polling suitability, and mentions an alternative access method via URL. However, it lacks explicit when-not-to-use or comparison to sibling tools.

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

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

Annotations indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds transparency about the tool making a single parallel call, fanning out to multiple data sources, handling rate limits via GDELT→GNews fallback, and the soft-fail for patents due to API sunset. No contradictions with annotations.

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

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

The description is front-loaded with example queries, which aids quick understanding. While it is relatively long, each sentence adds unique value (fallback behavior, source details, return format). It could be slightly more concise, but the structure is logical and well-organized.

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 specifies the return format: structured changes grouped by source, total_changes count, and pipeworx:// citation URIs. It also covers edge cases (soft-fail for patents, rate limiting). Given the tool's complexity (multiple sources, fallback), the description is sufficiently complete.

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

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

All three parameters are described in the schema (100% coverage). The description adds meaningful context beyond the schema, such as examples for 'since' ('7d', '30d', '3m', '1y'), recommending '30d' for typical monitoring, and clarifying that 'value' can be a ticker or CIK. It also notes that 'type' is limited to 'company'.

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

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

The description explicitly states the tool's purpose: provide a change feed for a company using multiple sources (SEC, GDELT/GNews, USPTO) in a specified time window. It uses specific verbs like 'fans out' and distinguishes itself from the sibling tool 'entity_profile', which provides a static profile.

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

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

The description includes clear usage guidance, including when to use this tool versus 'entity_profile'. It also describes fallback behavior (GDELT to GNews) and provides example query patterns ('What's new with X', 'latest on Y').

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 idempotent and non-destructive behavior; description adds scoping by identifier and retention policy (24 hours for anonymous), which is valuable beyond annotations.

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

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

Four sentences front-loaded with purpose, then usage, then technical details. No redundancy or wasted words.

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

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

For a simple tool with 2 parameters and no output schema, the description covers everything: purpose, when to use, pairing, persistence, and scope. 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% with clear descriptions; description adds naming conventions and value context but does not significantly surpass schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, with concrete examples (ticker, address, preference) and distinguishes from siblings recall and forget.

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

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

Explicitly states when to use ('discover something worth carrying forward'), provides pairing instructions with recall and forget, and explains persistence differences between authenticated and anonymous sessions.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds critical context: source-labeled identifiers, explicit `unresolved` reporting, ISIN-to-LEI mapping for foreign issuers, graceful degradation of enrichment, and internal cascading that replaces 2-3 manual lookups.

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?

Information-dense and front-loaded with examples and purpose, but long and runs as a single paragraph with dense prose. Every detail is relevant, though bullet points or clearer structural separation would improve scannability and reduce cognitive load.

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 exists, so the description carries the full burden of explaining return values. It names all identifier types (CIK, ticker, company_name, LEI, parent/ultimate-parent/children, FIGI, RxCUI, ingredient, brand) and covers failure/degradation behavior. For a multi-type, multi-source resolution tool, this is sufficient for correct 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?

Schema covers both parameters with an enum and value descriptions. The description adds substantial meaning: concrete examples (AAPL, 0000320193), accepted brand/generic names, and edge-case semantics such as ISIN resolving to the legal entity via GLEIF. This goes well beyond the schema.

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

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

The description opens with concrete user intents, then states the core function: resolve a user-spoken name to canonical/official identifiers other tools require. It enumerates supported types and explicitly positions it as the first step when a name but no ID is available, clearly distinguishing it from downstream tools like entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear trigger condition. However, it does not explicitly name alternative tools or describe when-not-to-use scenarios, so only partial exclusion guidance is provided.

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?

Describes internal use of ai_visibility_check and the output format (ranked list with score, confidence, signal density). Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature; description adds behavioral context without contradiction.

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

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

Three sentences, front-loaded with main action, no redundant information. Every sentence earns its 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?

Explains all necessary aspects: purpose, internal mechanism, output format. Schema covers parameter details; description adds narrative. No missing elements for a tool with no output schema.

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

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

Adds meaning beyond schema: clarifies first entity as 'subject' and rest as competitors, explains optionality of models array, and notes context is shared. Schema coverage is 100%, and description enriches parameter understanding.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. Distinguishes from sibling tools like ai_visibility_check (single entity) 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?

Provides context for use: competitive AI-marketing audits, with an example user query. Implicitly suggests when not to use (single entity) but does not explicitly mention alternatives or 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 behavior beyond annotations: fans out to deps.dev and bundlephobia, return format with specific fields, per-advisory details, links, alternative versions, and timeout possibility for bundlephobia. No contradiction with annotations.

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

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

The description is moderately concise and front-loaded with the main purpose. Though packed with information, it could be slightly restructured for easier reading, 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?

Given the complexity (multiple external sources, no output schema), the description fully explains return values, edge cases (partial failure, timeouts), and ecosystem scope. No gaps in context for an agent to understand the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description reiterates parameter meanings but adds no extra context beyond what the schema provides (e.g., scoped packages, default version).

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 ('check') and resource ('npm package'), clearly stating the composite nature and the external services involved. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on npm dependency evaluation.

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 ('is X safe / popular / small' or 'what does adding lodash cost me') and when not to use (NPM ecosystem only; directs to deps.dev:version for other ecosystems). Also describes partial failure behavior.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds specific behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping), character cap (200K with truncation flag), and output characteristics (offsets, similarity scores). Does not contradict annotations.

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

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

Single dense paragraph, front-loaded with the main action. Every sentence adds meaningful information—no filler. Efficient use of words to convey functionality, parameters, and use case.

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

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

No output schema, but description explains return types (passages with offsets and scores). Sufficient for an information retrieval tool with clear annotations. Could mention pagination or sorting, but not necessary given the simplicity.

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

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

Input schema has 100% coverage with descriptions for all 3 parameters. Description adds value with examples for query, default for limit, and technical context for text (embedding model, window size, cap). Surpasses baseline 3 by providing extra semantic meaning.

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

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

The description clearly states the tool performs semantic search within a fetched record, saving context by returning only relevant passages. It distinguishes itself from siblings by explicitly mentioning it pairs with ask_pipeworx_grounded and is used when the text is too large for the prompt.

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

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

Explicitly states when to use (when record is too big for prompt) and provides alternative (ask_pipeworx_grounded for grounding). Gives clear context on saving context and returning only relevant passages.

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=false, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds detail: requires OAuth account, behavior for each type, delivery constraints (phone verification, SMS cap, webhook signing, auto-disable). It does not mention idempotency or duplicate handling, which is a minor gap, but overall adds value beyond annotations.

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

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

The description is dense but well-organized: purpose first, then prerequisites, then types, then delivery. Every sentence adds value, though it could be slightly more concise (e.g., combining some details). No filler or redundancy.

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

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

Given 3 parameters (2 required), no output schema, the description covers purpose, prerequisites, type-specific behavior, delivery options, and channel constraints. It does not describe the full response structure beyond 'new subscription id' or error conditions, but is largely complete for usage.

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 enriches every parameter: 'type' gets examples and context (e.g., sec_8k items codes), 'params' gets detailed examples per type, 'delivery' gets constraints, webhook signing explanation, and auto-disable policy. This far exceeds schema-only info.

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 ('Create') and resource ('subscription to a live-data event stream'), clearly distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions', and mentions the return value (new subscription id). No ambiguity.

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 states prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channels. It gives usage context but does not explicitly exclude cases or mention alternatives, though sibling tools provide natural contrast. The guidance is clear for most scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable detail about output structure (category-bucketed examples with tool+argument shapes) and behavior (full spread vs focused). No contradictions.

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

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

The description is informative and well-structured with parentheses and dashes. While slightly long, every sentence adds value, so it earns its length. Could be tightened slightly without losing clarity.

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 (1 optional param, no output schema), the description is fully complete. It explains purpose, usage, output format, and parameter options. No gaps remain 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?

Schema coverage is 100% with a description for the single topic parameter. The description adds concrete examples of valid topic values and clarifies the effect of omitting the parameter, going beyond the schema's basic 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 clearly states it is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs ('returns', 'call') and distinguishes from sibling tools like ask_pipeworx by its discovery 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?

Explicitly advises 'Use this FIRST' when unfamiliar with Pipeworx, and explains when to omit vs specify topic. Does not explicitly list when not to use, but the guidance is sufficiently clear for an AI agent.

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

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

Adds context beyond annotations: deactivation vs deletion, ownership enforcement. Aligns with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) and clarifies non-destructive impact.

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

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

Two sentences, no fluff. Front-loaded with the action, then constraints and behavior. 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?

For a single-parameter tool with comprehensive annotations and no output schema, the description fully covers purpose, constraints, and behavioral consequences. 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% with a clear description of the 'id' parameter. Description adds no additional semantics beyond what the schema already provides, achieving 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?

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from siblings like subscribe and list_subscriptions by mentioning ownership enforcement and deactivation behavior.

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

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

Provides implicit guidance: ownership enforced (only cancel own subscriptions) and explains that historical events remain accessible via recent_alerts after cancellation. Does not explicitly contrast with alternatives but sufficient for a simple tool.

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

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

Annotations cover read-only, idempotent, and non-destructive traits, but the description adds substantial behavioral detail: it discloses the return verdict set, explains the meaning of could_not_verify (with verification_error) and unsupported, describes the internal routing logic, and notes that it replaces multiple sequential calls. This goes well beyond the annotations and gives the agent critical guidance on interpreting results.

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

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

The description is dense and front-loaded with trigger phrases and examples, making it efficient to parse. While it is longer than average, every sentence contributes essential information about behavior, return values, and edge cases. It could be slightly trimmed, but the length is justified by the tool's complexity.

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

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

Given the absence of an output schema, the description appropriately covers return values (verdict types, evidence, reasoning, error details), explains rare statuses (could_not_verify vs. unsupported), and describes the internal routing. The tool has only two parameters, and the description provides comprehensive guidance for both, making it complete for an agent to select and invoke correctly.

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

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

Although the schema already provides descriptions for both parameters, the description adds crucial context for tolerance_pct: it explains how the default is derived from claim wording, that it's capped at 5, and how setting it to 1–2 is recommended for hallucination detection. This added semantic depth helps agents decide when to override the default, exceeding the schema's bare 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 opens with natural-language trigger phrases ('Is it true that…', 'fact check') and clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It further distinguishes itself from sibling tools by specifying two distinct processing paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else) and by noting it replaces 4–6 sequential calls, making its unique role 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 explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the division between company-financial and other claims, but does not explicitly name alternative tools or mention when not to use it (e.g., for open-ended research). This is a minor gap, but the usage context is unambiguous.

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