Opensensemap

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

Adds valuable context beyond the annotations: default model (Workers AI Llama-3.3-70b, free), BYO Anthropic key with direct payment to Anthropic, and return structure. No contradiction with the readOnly/openWorld/idempotent annotations.

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

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

Three sentences, front-loaded with the main purpose, then additional details, then use cases. Every sentence contributes information without redundancy.

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

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

The description explains the default model, optional parameter behavior, and return format ({score, confidence, signals, raw_response} plus combined view). Given the tool's complexity and no output schema, this is sufficient for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the default model, that `_apiKey` is passed through to api.anthropic.com, and the cost implication of using Anthropic.

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 one or more LLMs for knowledge about an entity and scores visibility (0-100) per model. It mentions the default model and optional Anthropic integration, but does not explicitly differentiate from sibling tools like 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?

Provides clear use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies what the tool is for but does not explicitly say when not to use it or name alternative 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?

With annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable context: it fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is a fast single call. 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 long but every sentence serves a purpose: directive, scope, examples, comparisons, and fallback guidance. It is front-loaded with the key preference message, making it easy to scan despite its length.

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

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

Despite no output schema, the description explains what the tool returns (structured answer with citations), its broad coverage, and when to escalate to alternatives. For a complex routing tool with 1,412 sources, this is comprehensive and leaves no major gaps for an agent deciding to invoke it.

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

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

The schema already provides 100% coverage by documenting that 'question' accepts aliases (query, q, prompt, text, input). The description reinforces the semantic by giving natural language examples, but does not add new parameter-level detail 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 routes questions to the appropriate one of 5,439 tools across 1,412 sources and returns structured answers with citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose unmistakable.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). Includes concrete examples of when to use, such as 'current US unemployment rate'.

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, and idempotentHint, and the description does not contradict these. It adds valuable context beyond annotations by disclosing the beta/experimental nature, current inactivity of candidates, and that results feed into merge decisions. This enriches the behavior profile without overexplaining.

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

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

The description is compact and front-loaded with the core identity ('Beta version of ask_pipeworx'), then provides status, usage, and fallback in a logical order. It includes specific details like tool count and date, which add context without bloat. Each sentence serves a purpose, though slightly dense.

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, but the description states 'same response shape' as ask_pipeworx, covering return expectations. It addresses the beta context, current operational status, comparison to stable routing, and fallback behavior. For a universal router with complex routing logic, this is sufficient orientation for an agent.

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% and documents the 'question' parameter with all aliases. The description does not repeat parameter details, but it does mention 'same arguments' as ask_pipeworx, which is redundant given the schema. Baseline 3 is appropriate because the schema carries the full semantic load.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, with an identical universal router (same 5,439 tools, arguments, response shape). It distinguishes itself from the stable ask_pipeworx by mentioning experimental routing improvements and live candidate testing, providing a specific verb ('ask') and resource ('Pipeworx Beta').

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

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

Explicit usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide merges, implying when to choose this beta versus the stable sibling. The fallback is clarified as a full working router, not a thin wrapper.

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 key behavioral traits beyond annotations: returns a structured response with evidence and refusal reasons, never invents facts, and costs one extra LLM call versus ask_pipeworx. The readOnlyHint and idempotentHint annotations are consistent with the description, and the added operational details greatly enhance 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 dense but every sentence adds value: purpose, routing mechanism, return format, refusal reasons, use cases, and cost tradeoff. It is well-structured and front-loaded with the most important differentiator.

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 and the absence of an output schema, the description is remarkably complete. It specifies the exact success response shape, refusal reasons, and behavioral guarantees, fully covering what an agent needs to know to invoke and interpret the tool correctly.

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

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

The schema covers 100% of parameters, including aliases, so the description does not need to add parameter-level detail. The description mentions that the tool fills arguments internally, but this is not parameter-specific. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It explicitly distinguishes from sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior, making it easy to select the right tool.

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

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

Provides explicit guidance: use when answers will be quoted, cited, or acted on, and when hallucination is unacceptable. Also names the alternative (ask_pipeworx) and advises preferring it for casual lookups, giving clear when-to-use/when-not-to-use context.

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

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

The description goes far beyond the readOnlyHint and idempotentHint annotations, disclosing fan-out behavior, resolver contract (market_match_confidence, alternatives), safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread market handling, and cancellation-rule parsing. It even warns about blocking behavior and pure-rules loss. This is rich behavioral context that annotations alone could not infer.

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 uses clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every sentence carries specific, non-redundant details. It is front-loaded with the core purpose and input formats. While not terse, it earns its length given 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?

With no output schema and only basic annotations, the description must carry the full burden—and it does. It explains return fields, edge cases, error/blocking paths, resolution rules, and provides examples across multiple bet categories. Nothing critical is left unexplained.

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

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

Schema coverage is 100% with well-described parameters (market, depth, include_raw). The description reinforces the market input formats and gives examples, but it doesn't significantly extend the schema's meaning. The fan-out examples indirectly inform depth, but the schema already explains quick vs. thorough, so baseline 3 is appropriate.

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

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

The description leads with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly distinguishes it from sibling tools like polymarket_edges (which focuses on edges) and validate_claim (which validates claims). The scope and inputs are immediately evident.

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 use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This tells the agent when to invoke the tool, but it does not explicitly contrast with alternatives. Since the purpose is distinct and the context is clear, it meets the 'clear context, no exclusions' level.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is already clear. The description adds substantial behavioral context: it explains the data source (SEC EDGAR/XBRL), handles off-calendar fiscal years (AAPL Sep, NVDA Jan), states that results are sorted by the primary metric, and notes the return format (paired data + pipeworx:// citation URIs). This goes well beyond what annotations provide.

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

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

The description is dense and information-rich, with no filler sentences. Every clause adds value—trigger phrases, data sources, edge-case handling, sorting behavior, output format, and efficiency claim. It is slightly longer than the absolute minimum, but for a tool with two distinct modes (company vs drug) and such specific behaviors, the length is justified. The use of ALL CAPS for the key directive is a purposeful structural choice.

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

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

There is no output schema, so the description must cover the return value—and it does. It promises 'paired data + pipeworx:// citation URIs per entity' and details the metrics included per entity type, plus the sorting behavior. It also covers constraints (2–5 entities, one parallel call) and edge cases (off-calendar fiscal years). For a comparison tool of this complexity, this is complete enough for an agent to invoke it correctly and interpret results.

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

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

Although schema coverage is 100% (with a type enum and values array descriptions), the description enriches the parameter semantics significantly. It explains what each type actually retrieves (e.g., company → revenue, net income, cash, long-term debt; drug → FAERS adverse-event counts, FDA approvals, trial counts). It also clarifies that values must be 2–5 entities and that results are sorted by the primary metric, which helps the agent construct valid inputs and interpret outputs.

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

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

The description begins with a clear verb-resource pairing: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It includes multiple trigger phrases ('Compare X and Y', 'X vs Y', 'rank these companies'), making the tool's intent unmistakable. It also distinguishes itself from sequential single-tool lookups, a key differentiator from sibling 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?

The tool explicitly states when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This is a strong directive with an alternative (sequential lookups), and the description goes further to specify which entity types map to which data sources (company → 10-K metrics, drug → FAERS/FDA/trial counts). This leaves no ambiguity about the intended use case.

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

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

Beyond annotations that already mark it read-only, idempotent, and open-world, the description discloses account requirements, paid plan for 'thorough', latency expectations (15-60s), gap handling that never invents evidence, contradictions[] scanning, and semantic excerpting. These details add significant value and are consistent with the annotations.

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

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

The description is long but dense with information; each section (account, function, use cases, depth behavior, output details) earns its place. Some redundancy exists between the depth parameter schema and the description's repetition of hop mechanics, but the overall structure is well-organized and front-loaded with the most critical caveats.

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 compensates fully by describing the findings packet, citation_uri, gaps[], contradictions[], and hop field. It covers auth, latency, alternatives, and limitations (structured catalog gaps), making it comprehensive for a complex research tool.

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

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

The schema already covers both parameters thoroughly (100% coverage), including the depth enum semantics with detailed descriptions. The description adds latency expectations and reiterates the paid plan for 'thorough', but mostly repeats schema details, providing only marginal extra meaning beyond what the schema already provides.

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

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

The description clearly states it performs 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources' in one call, decomposing questions into facets. It explicitly distinguishes itself from ask_pipeworx and open-web search, making the purpose unmistakable.

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

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

It explicitly explains when to use this tool: 'Best for broad/multi-part questions over structured data' and when not: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides a fallback if not signed in ('use ask_pipeworx instead'), giving clear decision criteria.

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?

Given annotations already declare readOnly, idempotent, and non-destructive behavior, the description adds valuable behavioral context: returns top-N relevant tools with names, descriptions, full input schemas, curated examples, and no second schema lookup needed. This transparently sets expectations about output format and usability without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value: purpose, domain scope, return behavior, and usage timing. It is appropriately sized for a meta-tool and avoids redundancy with structured fields.

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 thoroughly explains what the tool returns (names, descriptions, schemas, examples, and direct callability). The tool's complexity is moderate, and parameters are fully covered by the schema. The description provides enough context for an agent to select and invoke the tool correctly without ambiguity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and aliases. The description adds minimal parameter-specific detail beyond implying that 'query' is the natural-language description and 'limit' controls the top-N count. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a meta-tool that discovers other tools. The verb 'discover' and resource 'tools' are explicit, and the scope is well-defined.

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 strong contextual guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies when to use it, but does not explicitly name alternatives or exclusions. It does mention that returned tools are ready to call directly, which indirectly directs the next step.

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 the parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF, and the soft-fail behavior of the patents component ("USPTO PatentsView API sunset May 2025 — soft-fails until reactivated"). It also specifies the exact fields returned, which adds value beyond the readOnlyHint annotation.

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

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

The description is longer than average but every sentence earns its place: examples, preference rule, return contents, limitation, and fallback. It is front-loaded with user intents and the key directive. Slightly compressed but justifiably detailed.

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 multi-source complexity and lack of output schema, the description thoroughly covers inputs, outputs, limitations, and fallback behavior. It provides sufficient context for an agent to decide and invoke without additional investigation.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the parameter guidance (ticker or CIK, names not supported) but adds no new semantic detail beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: "full cross-source profile of a US public company in ONE parallel call." It provides concrete example queries ("Tell me about X", "research Acme") and enumerates the data types returned (CIK, filings, fundamentals, patents, news, LEI). This distinguishes it from siblings like compare_entities or ask_pipeworx.

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

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

Explicit usage guidance is given: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also tells when not to use it: "names not supported (use resolve_entity first if you only have a name)." This clearly directs the agent 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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds minimal extra behavioral context (e.g., 'clear sensitive data' implies irreversible deletion), but doesn't disclose additional traits beyond the annotations, such as whether deleting a non-existent key is an error or a no-op (idempotentHint is already set).

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

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

The description is two sentences long, front-loaded with the core purpose, and every phrase adds value. It is concise and well-structured, avoiding any fluff.

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

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

Given the tool's simplicity (one parameter, no output schema) and the presence of accurate annotations, the description fully covers what the agent needs: what it does, when to use it, and how it relates to siblings. No missing critical information.

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

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

The schema provides 100% coverage for the single parameter 'key' with a clear description ('Memory key to delete'). The tool description adds no additional semantic meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource. It distinctively contrasts with sibling tools like remember (store) and recall (retrieve), making the tool's purpose unambiguous.

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

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

The description explicitly specifies when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with remember and recall, providing useful context, though it doesn't explicitly state when not to use it. This is strong guidance 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 already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read-only operation. The description adds value by disclosing that the tool 'Fetches the page' (network access) and 'emits the standard llms.txt markdown format' as output, which are behaviors not inferable from annotations alone.

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

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

The description is three sentences plus a use-case list, with no redundant phrases. It is front-loaded with the main purpose and each sentence adds distinct information: action, mechanism, output, and scenarios.

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

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

With no output schema, the description fully explains the return value: 'a single text blob ready to drop at site-root/llms.txt'. Combined with the rich annotations and explicit behavior, this provides a complete picture for an agent to invoke the tool correctly.

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

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

The schema covers both parameters (url and max_links) with clear descriptions at 100% coverage, so the description doesn't need to add parameter details. It adds minimal extra meaning beyond the schema, like mentioning 'link entries' correlates with max_links, but this is marginal. Therefore a 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 a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It further explains the mechanism (fetches page, extracts title/description/key links) and the output format, making it easily distinguishable from sibling tools.

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

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

The description provides concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It lacks explicit exclusions or alternatives, but given the uniqueness of the tool, these scenarios sufficiently guide when to use it.

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

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

Annotations already mark this as readOnly, idempotent, non-destructive. The description adds that it returns the caller's subscriptions (auth scope) and enumerates the exact return fields, which is useful behavioral context beyond the annotations. 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 short sentences: purpose, return fields, usage. Each sentence adds new information. No filler or repetition.

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

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

Given the tool's simplicity, the description is sufficient: it states what it lists, what it returns, and when to use it. The schema covers the optional parameter, and annotations cover safety. No output schema exists, but the return fields are explicitly enumerated.

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

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

The only parameter (include_inactive) is fully described in the schema, covering its purpose and default. The description doesn't add parameter-specific details but doesn't need to given the schema provides complete information. Baseline score 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 starts with a clear verb ('List') and resource ('the caller's active subscriptions'), and explicitly lists return fields. The sibling context includes subscribe/unsubscribe, and the description mentions using this to review before adding more or to find an id to cancel, distinguishing it from those siblings.

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

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

It provides explicit use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to call it relative to subscribe/unsubscribe, fulfilling the usage guideline requirement.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds valuable context beyond these: 'Aggregates the latest reading per sensor over the recent window client-side (the network has no fast server-side aggregation)' and the strict requirement that 'the name must match the sensor title exactly'. It also lists exact German phenomenon names with units, giving the agent critical operational knowledge.

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

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

The description is front-loaded with the core purpose and includes essential details (usage modes, aggregation behavior, phenomenon list, example). It is longer than strictly necessary but every sentence contributes useful information, with no filler. The structure is logical, moving from what to how to example.

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?

Input semantics are thoroughly covered, but there is no output schema and the description does not state what the tool returns (e.g., whether it's a single average number, an object with sensor count, or units). Edge cases like empty areas or invalid phenomenon names are also not addressed. For a tool with this complexity and no output schema, the description is incomplete on the output side.

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 6 parameters at 100% coverage, so the baseline is 3. The description adds significant meaning beyond the schema by providing an exhaustive list of exact phenomenon names with units (e.g., 'Temperatur' (°C), 'PM2.5' (µg/m³)), explaining the exact-match requirement, and giving an example call that demonstrates how parameters combine. This pushes it above baseline.

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

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

The description clearly states the tool's function: 'Average one phenomenon across all citizen science sensors ... in an area'. It specifies the verb (average), resource (phenomenon across sensors), and scope (area), and distinguishes it from sibling tools like opensensemap_box and opensensemap_nearby by emphasizing area-based aggregation with bounding box or center+radius input.

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

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

The description gives clear usage context: 'Give either a bounding box or a center point + radius_km' and explains the client-side aggregation window. However, it does not explicitly mention alternatives or when not to use this tool compared to related opensensemap tools, so it falls short of a full 5.

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

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

Annotations already declare the read-only and idempotent nature. The description adds the important caveat that sensors are community-operated and uncalibrated, which is behavioral context about data reliability not covered by annotations.

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

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

Three sentences and an example; all parts are meaningful. The purpose is front-loaded, the source of ids is briefly mentioned, and the caveat adds value without verbosity.

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, read-only annotations, and no output schema, the description sufficiently covers what data is returned (sensor readouts, location, exposure, metadata) and provides usage context. It is complete enough 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 coverage is 100%, providing the parameter name and type. The description enhances this by specifying that box ids come from opensensemap_nearby and including a concrete example, making the parameter's origin and format clearer.

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 'get' and the resource: a single openSenseMap station by box id. It distinguishes from sibling tools by highlighting the box id lookup and the specific fields returned.

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 that box ids come from opensensemap_nearby, guiding the agent on when to use this tool versus the sibling nearby tool. The description also makes clear that this returns detailed single-station data, implying it is not for area averages.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds meaningful beyond-annotation context: community-operated uncalibrated hardware with varying quality, a 7-day stale-skipping rule, and the ability to include stale stations. 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 the main purpose, then provides natural-language usage, data-quality caveat, parameter guidance, behavior, and an example. Every sentence serves a purpose; length is justified by the complexity of the phenomenon names and filtering behavior.

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 read-only nearby-search tool with no output schema, the description covers the key aspects: what it returns (latest readings across various measurement types), filtering via phenomenon, stale-station behavior, data-quality caveats, and a concrete example. It is complete enough 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?

Schema coverage is 100%, but the description adds significant value by explaining the phenomenon parameter with exact German names and units, clarifying the substring case-insensitive matching, and illustrating with an example. This goes well beyond the schema descriptions.

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

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

The description states a specific verb+resource: 'Find citizen science sensor stations... near a lat/lon and return their latest readings.' It clearly distinguishes from sibling tools by emphasizing the 'near a lat/lon' point-based search, and provides concrete natural language queries it answers.

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: 'Answers "sensor readings near me"...' and filters for phenomena and stale stations. It does not explicitly mention alternatives like opensensemap_area_average or opensensemap_box, but the 'nearby' framing implies 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 provide almost no behavioral hints (all false), so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), team review cadence ('digests daily'), and content guidance ('don't paste the end-user's prompt'). These are actionable behavioral traits not present in the annotations or 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?

Though the description is lengthy, every sentence carries operational value: purpose, when-to-use, exclusions, scope clarification, content format, rate limit, and quota impact. It is front-loaded with the core purpose and efficient, containing no filler or redundancy.

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

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

For a feedback tool with 3 parameters (one nested object) and no output schema, the description covers all necessary context: what to communicate, how to scope feedback, when to avoid, rate limits, quota, and team behavior. It is complete without needing schema or annotations.

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

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

Schema coverage is 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds meaningful extra guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and the context of scope, raising it above the baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies a specific verb+resource (send feedback to Pipeworx team) and distinguishes it from sibling tools like ask_pipeworx by focusing solely on feedback. The opening sentence immediately conveys what the tool 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 provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives explicit exclusions and alternatives: 'if the tool came from a different MCP server... file it with that server instead.' This is comprehensive and 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds substantial transparency beyond that by disclosing the data source ('derived from CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h depending on window'). This enriches the behavioral profile considerably.

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

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

The description is front-loaded with a clear one-sentence summary, followed by a numbered list of use cases, and a concise data-source/privacy footer. Each section earns its place and there is no redundant phrasing, making it appropriately sized and easy to scan.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is remarkably complete. It covers return contents, use cases, data provenance, privacy, and caching, which is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema fully documents the single optional 'window' parameter with enums and semantics about shorter vs longer windows. The description adds that caching varies by window (5min-1h), which is useful additional context. With 100% schema coverage, the baseline is 3, but this extra detail justifies a 4.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' It also frames the purpose as 'What other AI agents are calling on Pipeworx right now,' which is specific and distinguishes it from siblings like discover_tools or ask_pipeworx.

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

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

The description provides three explicit use cases, such as discovering hot data sources and confirming a popular tool before asking a question. It gives clear context on when to use the tool but does not explicitly mention alternatives or when not to use it, so it misses the top score.

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

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

Despite annotations declaring read-only/open-world/idempotent, the description adds substantial behavioral context: the partition filter (drops placeholder slugs, >20% placeholder fraction returns null), the fill check against live CLOB depth, and the distinction between theoretical_edge_pp_at_book and realizable_edge_pp. It even warns 'do not trade it' when realizable edge ≤ 0. This greatly exceeds annotation coverage.

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

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

The description is a dense, one-paragraph block with semicolons and nested clauses, making it hard to parse quickly. While every clause adds useful detail, it lacks bullet points or clear section breaks that would improve scannability for an AI agent. It is informative but not concise.

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

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

There is no output schema, so the description must explain return values, which it does by specifying `opportunities[]` fields, `partition_check` fields, and the fill-check output. It covers edge cases like placeholder filtering and similarity thresholds. Minor gaps include exact error behavior, but for a complex tool it is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics beyond the schema: it explains that `event` takes an event slug or full URL, `topic` is a seed question for cross-event scanning, and gives concrete examples like 'fed-decision-may-2026' and 'Strait of Hormuz traffic returns to normal.' This is a meaningful enhancement.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from siblings like polymarket_fill_risk and polymarket_edges by describing its unique approach and explicitly differentiating the event and topic modes.

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 each mode: 'Call with NO args for a trending_scan,' '`event` (recommended for a specific market),' and '`topic` (for cross-event scanning).' It also names an alternative tool: 'For custom sizing use polymarket_fill_risk.' This is clear and actionable.

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 extensive behavioral traits beyond the simple readOnly/idempotent annotations: it details the five model families, how edges are computed (e.g., slippage subtraction, Kelly cap), the caching behavior ('Cached 1h at the KV level keyed on all knobs'), and why segments might be empty. This gives the agent a deep understanding of what happens when invoking the tool.

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 appropriately detailed for a complex tool. It is front-loaded with purpose, and uses clear uppercase section headers (e.g., 'TRADEABLE-EDGE KNOBS:', 'RESPONSE TOP-LEVEL:') to organize dense content. However, some sentences are overly long and parenthetical-heavy, slightly reducing readability.

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

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

With no output schema, the description bears the full burden of explaining return values. It thoroughly describes the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), the fields carried by every opportunity, the meaning of filter_skips, and the caching behavior. This is a complete and self-sufficient description for an agent.

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

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

The input schema already has 100% description coverage, so the baseline is 3. The tool description adds only a high-level summary of the tradeable-edge knobs ('min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') without introducing new factual details beyond what schema descriptions already provide.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and distinguishes it from sibling tools by focusing on Pipeworx-derived edges and discovery without paging hundreds of markets.

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: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains why certain content (Fed bets) is excluded from ranking. However, it does not explicitly state when not to use this tool or name alternative sibling tools, so it falls short of a 5.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing data source, snapshot behavior (cache-miss writes), TTL limits, decay computation method (daily closes of edge_pp_net, not intraday), and interpretation of gaps in snapshot_dates. It also explains the meaning of expired[] opportunities and the 'competition clock'. This is rich behavioral context that fully informs the agent.

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 with clear sections (Args, RESPONSE, LIMITS) and is front-loaded with the core purpose. It is dense but every sentence contributes useful information, including the explanatory metaphor about the edge being wide 'for a reason nobody is willing to take'. However, it contains some redundancy (e.g., repeating 'snapshot' frequently) and could be slightly tightened without losing value.

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

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

Given the absence of an output schema, the description provides an extensive account of the response structure (tracked[], expired[], snapshot_dates[]) with field-level details (first_seen, trend, decay_pp_per_day, lifespan_days). It also covers limitations (60-day TTL, snapshot start time, daily closes). This is exceptionally complete for a telemetry tool with two parameters and no output schema.

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

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

The schema has 100% description coverage for both parameters (days and window), so the baseline is 3. The description repeats the defaults and meaning ('days (lookback, default 14, max 30)', 'window (snapshot family, default "1wk")') but does not add new semantics beyond what the schema already provides. The schema already includes clamping details and allowed values for window, so the description adds minimal extra 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 the tool's purpose: edge persistence and decay telemetry built from daily polymarket_edges snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling polymarket_edges tool by focusing on historical tracking rather than current edges. The verb 'Answers' and resource definition make it unambiguous.

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

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

The description provides clear context for when to use the tool: when you need to know edge persistence, decay, or whether an edge is aging. It mentions 'a fresh wide edge and a 3-week-old wide edge are different trades', which implies a use case for evaluating edge quality over time. However, it does not explicitly mention alternatives or exclusions (e.g., 'use polymarket_edges for current edges'), so it lacks explicit when-not-to-use guidance.

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

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

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds rich behavioral context: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp), and explains basket mode's forced directional risk. This goes far beyond the annotations and helps the agent understand the tool's non-obvious behavior.

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

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

The description is long but every sentence earns its place. It is structured with explicit labels (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) that make it scannable. Despite the length, there is zero fluff and the information density is high, appropriate for a complex tool with two modes.

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

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

Given no output schema and no nested objects, the description carries full burden for understanding return values and edge cases. It covers both modes, parameters, default behaviors, output fields, risk warnings, and usage thresholds. This is complete for the tool's complexity.

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

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

Although schema coverage is 100%, the description adds meaning by explaining how size_usd is interpreted per mode ('max spend on buys, target proceeds on sells' vs 'settlement notional S'), and clarifies the side parameter's defaults and auto-selection in basket mode. This provides context that the schema alone lacks.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by focusing on fill risk versus theoretical edge, and explicitly names both modes (single-market and basket) with concrete outputs.

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

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

Usage is explicitly stated: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills create directional risk), making the context and exclusions 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?

The description extensively discloses behavior beyond the read-only annotations, including compatibility_warning conditions, temporal_alignment details, and skipped_cross_type/subtype counters. It clearly explains when spreads are meaningful and when they are not, such as with non-equivalent bet shapes or temporal misalignment. This exceeds the baseline set by annotations and provides critical context for 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 lengthy but well-structured with clear labels for modes, response, and safety fields. It packs substantial information about caveats and edge cases into a dense, organized format. While somewhat verbose, each sentence serves a purpose in clarifying the tool's complex behavior.

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 thoroughly covers the response format (leg prices, spread values) and safety fields (compatibility_warning, temporal_alignment, skipped counters). It also gives real-world context about the rarity of tradeable spreads, making it complete for a complex tool. The read-only annotations and complete schema coverage together with this description provide a robust understanding.

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

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

The input schema already describes all three parameters with examples, giving 100% coverage, so baseline is 3. The description adds value by explaining how the parameters interact: topic auto-fetches a mapped event, while explicit tickers/slugs override that mapping for custom pairings. This semantic guidance on mode selection goes beyond the schema.

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

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

The description clearly identifies the tool as computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It details the two modes and the response contents, making the tool's function unambiguous. Although it doesn't name sibling tools explicitly, the focus on cross-venue comparison distinguishes it from Polymarket-only tools like polymarket_arbitrage.

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

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

The description explains two usage modes: pre-mapped topic shortcuts for common macro events and explicit ticker/slug for custom pairings. It also warns that pre-mapped topics often return compatibility_warning and are not necessarily tradeable, which guides when not to rely on the tool. However, it does not compare against specific alternative tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it explains the 'list all keys' behavior when the key argument is omitted, the scoping to an identifier, and the complementary relationship with remember and forget. This goes beyond the minimal annotation coverage without contradicting it.

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

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

The description is two sentences long, front-loads the primary action, and packs useful details (examples, scoping, sibling pairing) without padding or repetition. 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?

This is a low-complexity tool (one optional parameter, no output schema). The description covers what it returns (a value or list of keys), when to use it, how it's scoped, and how it relates to sibling tools. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples of what keys might contain ('user's target ticker, an address, prior research notes'), which helps the agent form a mental model of valid inputs. It also clarifies the omit-key behavior for listing, which the schema already states but the description reinforces with context.

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

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

The description starts with a specific verb 'Retrieve' and clearly states the resource (values previously saved via remember) and the dual behavior of listing all keys when the argument is omitted. It inherently distinguishes itself from sibling tools 'remember' and 'forget' by describing its read-only retrieval 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?

The description explicitly says 'Use to look up context the agent stored earlier' and then pairs the tool with 'remember to save, forget to delete.' This provides clear when-to-use guidance and implicitly states when not to use (for saving or deleting). The scoping note (anonymous IP, BYO key hash, account ID) adds important context.

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

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

Annotation Contradiction: readOnlyHint=true conflicts with the description's claim that setting mark_read:true flags events as read and affects future calls, which is a write to the persisted feed. The description also adds other context like polling, but the contradiction forces a score of 1.

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

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

The description is compact and front-loaded with the purpose, then provides return details and usage tips. The final sentence is slightly dense with multiple clauses, but every sentence carries useful information.

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 covers return fields (source, citation_uri, payload), read semantics, and alternative access. It doesn't mention unread_only or pagination, but given the simple structure and full schema coverage, it's reasonably 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 covers all parameters (100%), but the description adds value by providing an example type ('sec_8k'), clarifying the since format (ISO timestamp), and explaining the behavioral effect of mark_read. This goes beyond the schema's basic descriptions.

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

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

The description opens with a specific verb and resource ('Pull fired events from your subscription feed'), clearly distinguishing it from siblings like list_subscriptions or recent_changes. It states the core action and what it returns.

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

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

It explains the polling use case and points to an HTTP endpoint for scripts/dashboards, offering an alternative. However, it doesn't explicitly say when to use this tool versus sibling tools like recent_changes, so it lacks explicit exclusions.

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

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

The description discloses behavioral traits well beyond the annotations: it mentions parallel fan-out to SEC EDGAR, GDELT/GNews fallback, USPTO patent source with a note about API sunset and soft-fail, plus the return format (changes[], total_changes, citation URIs). This provides rich context that annotations (readOnly, openWorld, idempotent) do not cover. 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 example queries, then states the core purpose, then provides source/fallback details, parameter format, return structure, and alternative tool. Every sentence adds value, and the length is justified by the tool's complexity. It is not bloated or redundant.

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

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

Given there is no output schema, the description sufficiently explains the return value (changes[], total_changes, pipeworx:// citation URIs). It covers sources, fallback behavior, date format, and explicitly contrasts with entity_profile, 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?

While schema coverage is 100%, the description adds extra meaning: it explains `since` accepts ISO date or relative shorthand with concrete examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for monitoring. This goes beyond the schema's description of `since` as 'Window start'.

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

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

The description clearly states this is a change feed for a company over a time window, with specific verb 'change feed' and resource 'company'. It distinguishes itself from the sibling entity_profile by explicitly saying 'Use entity_profile instead for the static profile', and provides example queries showing its purpose.

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

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

The description provides explicit usage guidance: it names entity_profile as the alternative for static profiles regardless of window, and gives example query phrasings ('What's new with X') to indicate when to use this tool. It also explains the fallback behavior (GDELT to GNews on rate limit/5xx), which helps decide when to invoke it.

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

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

Annotations already note idempotent and non-destructive; the description adds rich context: key-value pair scoping by identifier, persistent vs. 24-hour retention based on auth, and pairing with recall/forget. No contradiction with annotations.

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

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

Three concise sentences, front-loaded with purpose, then usage guidance, then storage details. Every sentence earns its place with no redundancy.

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

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

For a simple key-value store with no output schema and full parameter coverage, the description fully addresses scope, durability, and companion operations. The agent has enough context to use the tool correctly and decide when to invoke it.

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

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

Schema coverage is 100% with detailed descriptions for both key and value. The description reinforces the key-value concept and gives examples, but adds no new syntax or formatting details beyond what the schema already provides.

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

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

Description opens with a specific verb and resource ('Save data the agent will need to reuse later'), clearly distinguishing it from recall (retrieve) and forget (delete). The scope ('across this conversation or across sessions') further clarifies its role.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Does not explicitly state when not to use, but the companion tools (recall, forget) are referenced, giving clear complementary context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by explaining that the tool cascades through multiple lookup endpoints internally, supports auto-disambiguation, and returns citation URIs. This goes beyond what annotations provide, though it doesn't discuss potential errors 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?

The description is long but well-structured and front-loaded with natural language examples. It includes essential details like supported types and return values without unnecessary fluff. Each sentence serves a purpose, though a bit more editorial trimming could make it even tighter.

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

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

Given the tool's complexity (two entity types, multiple input forms, no output schema), the description is remarkably complete. It details the returned fields for both company and drug, mentions citation URIs, auto-disambiguation, and internal cascading. It adequately covers what the agent needs to know for correct invocation and expectation setting.

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

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

Schema coverage is 100% with descriptions for both parameters, but the description adds significant context beyond the schema. It explains the return types tied to each enum value for 'type' and gives concrete examples of accepted forms for 'value' (ticker, CIK, brand/generic name). This enriches the parameter semantics 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 uses a specific verb ('resolve') and clearly defines the resource: converting user-spoken names into canonical/official identifiers required by other tools. It distinguishes itself from siblings by explaining that it supplies IDs that other tools need, and provides concrete example queries, making its purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is strong usage guidance. It also clarifies supported entity types and input formats, implying when it applies. It does not explicitly state when not to use it, but the directive to use it first in ID-requiring scenarios 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, openWorldHint, idempotentHint, and destructiveHint, so the description only needs to add context. It does by describing the probing process, ranking logic, and output fields (score, confidence, signal density). It does not mention potential rate limits or the number of API calls, but for a read-only tool this is adequate.

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

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

The description is three sentences, front-loaded with the primary action, then the process, then a use-case example. Every sentence carries meaning, and there is no redundant repetition of schema or annotation information.

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 moderate complexity (multi-entity, calls another tool, no output schema), the description covers the core behavior, return format, and use case. It could mention the per-probe API call overhead or error conditions, but the essential information 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?

Schema description coverage is 100%, so per rubric the baseline is 3. The description references entities, models, and _apiKey in prose but adds no syntax or format details beyond what the schema already provides. It does not compensate further for any missing 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 clearly states a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), and distinguishes itself from the sibling tool ai_visibility_check by focusing on multi-entity comparison and ranking. It also differentiates from the generic compare_entities by specifying the exact domain and output.

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

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

The description provides explicit use-case context ('competitive AI-marketing audits') and explains the mechanism (probes entities with ai_visibility_check and ranks them), making it clear this is for multi-entity comparisons. It does not explicitly state when not to use it or list alternative tools, 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 mark readOnly and idempotent, but the description adds critical behavior beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. It also discloses the output structure including summary fields, per-advisory detail, links, and alternatives. This is rich, non-obvious 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 lengthy but every sentence earns its place. It is front-loaded with the core purpose, then use cases, then output summary, then ecosystem scope, then failure behavior. The structure is logical and skimmable despite its length.

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

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

Given the tool's complexity (composite of two external APIs) and the absence of an output schema, the description thoroughly explains what the tool returns (summary block with specific fields, per-advisory detail, links, and recent versions). It also covers ecosystem limitations, latency, and graceful degradation. This is 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?

The input schema already provides 100% coverage for both parameters, with detailed descriptions for 'package' (including scoped packages) and 'version' (including default behavior). The tool description adds no additional parameter semantics beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'scan' and the resource 'dependency', and explains it is a composite check across deps.dev and bundlephobia. It differentiates from siblings by explicitly limiting to NPM and pointing to deps.dev:version directly for other ecosystems. Concrete use cases like 'is X safe / popular / small' make the purpose unambiguous.

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

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

Provides explicit triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion and alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. This clearly tells when to use this tool and when not to.

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/non-destructive, so the description focuses on revealing processing details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows' and the 200K char truncation limit. It also discloses output structure (offsets, similarity scores) and the verifiability point. This goes well beyond the annotations.

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

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

The description is compact at ~5 sentences, with the purpose front-loaded in the first sentence. Each subsequent sentence adds a distinct aspect (usage case, pairing, technical limitation), and there is no repetition or filler.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does: 'top-N passages with character offsets and similarity scores.' It also covers the transformation (embeddings, windows), the cap, and the pairing workflow, making it self-sufficient for an agent to decide and invoke.

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 each parameter is already documented. The description adds contextual examples for 'text' (SEC 10-K body, article, long tool result) and reinforces the query's natural-language form, but doesn't introduce any syntax or format details beyond the schema. This meets the baseline for high coverage.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource pairing that immediately distinguishes it from siblings like ask_pipeworx or validate_claim. It also explicitly states the input (text+query) and output (top-N passages with offsets and similarity scores), leaving no ambiguity about what the tool 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 gives an explicit condition: 'Use when the record is too big to cram into the prompt.' It also positions the tool relative to ask_pipeworx_grounded, explaining how to pair it: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This is clear when-to-use guidance with an alternative.

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

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

Beyond annotations, it adds auth requirements, inability for anonymous/BYO accounts to persist, return of subscription id, feed always on, SMS verification and 10/day cap. These significant behavioral traits are not in annotations and are useful for an agent.

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

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

The description is a dense but organized paragraph with purpose, auth, types, and delivery channels. It stays compact for the amount of information, though a little heavy with inline JSON examples.

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?

It covers the essential context: return value, auth, subscription types, delivery options and constraints. It omits the webhook delivery channel from the main text, but the schema describes it, so overall with schema it is complete.

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

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

The input schema already documents all parameters and nested objects with 100% coverage, including examples for each type. The description adds a couple of semantic clarifications (e.g., sec_8k item mapping) but does not substantially expand parameter understanding beyond the schema baseline.

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

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

The description begins with 'Create a proactive monitoring subscription to a live-data event stream' – a specific verb, resource, and purpose. It also names supported subscription types and distinguishes from sibling tools like list_subscriptions and recent_alerts.

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

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

It clearly states the use case (proactive monitoring), prerequisites (OAuth account), and delivery model. It mentions recent_alerts/registry feed for retrieving events, implying when the feed is used, but does not explicitly explain when NOT to use this tool vs alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds behavioral detail: it returns category-bucketed examples drawn from the live catalog, supports optional topic filtering, and serves as a learning aid for meta-tools. No contradictions.

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

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

The description is longer than average, but it is front-loaded with example queries and each section (return format, topic parameter, usage context) earns its place. The list of categories is somewhat verbose but 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?

For a tool with one optional parameter and no output schema, the description is remarkably complete: it explains the return structure (category-bucketed examples with tool+argument shapes), the source (live catalog), and when to invoke it. There's no ambiguity about invocation or expected output.

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

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

Schema covers the single optional 'topic' parameter 100% with allowed values. Description adds practical nuance: omitting topic yields a cross-category spread, while passing a topic focuses results, with concrete examples like 'finance' and 'betting'.

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

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

The description clearly states the tool is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It uses a specific verb ('suggest_questions') and distinguishes from siblings by saying 'Use this FIRST' and referencing meta-tools like ask_pipeworx 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?

Explicit usage guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the no-arg vs topic parameter choice and gives example queries.

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

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

The description discloses key behavioral traits beyond annotations: ownership enforcement ('you can only cancel your own subscriptions') and non-destructive deactivation ('The row is deactivated (not deleted) so its historical events stay available via recent_alerts'). These align with destructiveHint=false and add 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 two sentences, front-loaded with the action and then constraints. No unnecessary 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 one-parameter mutation tool with no output schema, the description covers the important side effects: deactivation and preservation of historical events. It does not specify return values or error cases, but annotations provide idempotency and open-world hints.

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 the id parameter fully (100% coverage) with a description referencing subscribe. The tool description adds the ownership constraint that the id must belong to the caller, which adds meaning beyond the schema.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It uses a specific verb and resource, and it distinguishes from siblings like subscribe and list_subscriptions by specifying the cancellation semantics.

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

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

The description implies when to use (when you want to cancel a subscription) but does not explicitly compare to alternatives. It mentions ownership enforcement, which is a constraint, but does not say 'use this instead of list_subscriptions' or similar.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant context beyond that: mentions the grounded pipeline, verbatim evidence, verdict types, structured vs grounded paths, exact percent-delta math, and pipeworx:// citations. This is rich behavioral disclosure and does not contradict annotations.

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

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

The description contains valuable information but is written as one long run-on sentence with multiple clauses and digressions, making it harder to parse. While each piece of information earps its place, the structure could be improved with separate sentences or bullet points. It is longer than necessary but not excessively wasteful.

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

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

Despite having no output schema, the description explicitly lists return components (verdict, actual value, citation, reasoning). It covers routing logic, claim types, parameter behavior, and the tool's advantage over sequential calls. Given the tool's complexity, the description is complete and self-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?

Schema covers all 2 parameters with descriptions, but the description adds extra semantic value for tolerance_pct: 'set 1–2 for hallucination detection' and explains default behavior ('implied by wording, capped at 5'). Claim examples are also provided. This exceeds the baseline for high schema coverage.

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

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

Description uses specific verbs like 'verify', 'fact check', and 'confirm or refute', clearly identifying the tool's purpose. It lists natural-language phrasings and explicitly states it checks whether something is factually correct. It distinguishes from siblings by describing unique routing (SEC EDGAR vs grounded pipeline) and claims to replace 4–6 sequential calls.

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

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

Provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' Describes routing logic for company-financial claims vs other factual claims, making the use case clear. Does not explicitly name alternative tools or when-not-to-use scenarios, so not a 5.

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