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?

The annotations already establish read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context beyond that: it routes to 5,706 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier in one call. No contradiction with annotations.

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

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

The description is long but deliberately structured: it front-loads the preference over web search, then gives domain scope, trigger phrases, examples, and escalation guidance. Minor redundancy exists between 'PREFER OVER WEB SEARCH' and 'START HERE', but overall every section serves a purpose.

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

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

Given the rich annotations, full schema coverage, and the description's coverage of when to use it, how it operates, what it returns, and which siblings to escalate to, nothing critical is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, and the schema already documents the question parameter and all aliases. The description provides helpful example queries but no additional semantic depth beyond what the schema already conveys, 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 ask_pipeworx is the default factual question-answering tool, enumerates the domains it covers, and explicitly contrasts it with sibling tools like ask_pipeworx_grounded and deep_research. This makes its purpose immediately distinguishable.

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

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

It gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with concrete criteria for choosing ask_pipeworx_grounded versus deep_research. It even addresses the breaking-news edge 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?

The description goes beyond the readOnly/openWorld/idempotent annotations by disclosing that candidate routing improvements can be enabled live, that no candidate is currently active so it matches ask_pipeworx exactly, and that it is a full working router rather than a fallback stub. This is valuable behavioral context 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 compact and front-loaded with the key fact ('Beta version of ask_pipeworx'), then packs only the essential caveats: identical surface, no active candidate, usage instruction, and 'full working router' reassurance. Every sentence contributes; there is no filler.

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

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

Given the tool's role as a universal router with no output schema, the description covers what an agent needs: identity, current operational state, relationship to ask_pipeworx, and how to invoke. The missing explicit return-format details are mitigated by 'same response shape' as the stable sibling, though a broader output example would make it fully 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?

All six parameters are fully described in the schema as aliases for question, so the 100% schema coverage establishes the baseline. The description adds only that the arguments are the same as ask_pipeworx, which supports cross-reference but does not deepen parameter 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 explicitly identifies this as the beta version of ask_pipeworx and a universal router with the same 5,706 tools, arguments, and response shape, while distinguishing it as the experimental edge. This gives a specific purpose and differentiates it from the stable ask_pipeworx sibling.

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

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

It explicitly directs the agent to use it exactly like ask_pipeworx when the newest routing is desired, and explains results are compared to the stable router to decide merges. It could be more explicit about when to prefer the stable sibling, but the 'when you want the newest routing' condition supplies clear 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 cover read-only/idempotent safety, but the description adds substantial behavior beyond that: the exact success contract, the refusal contract with its five enumerated refusal_reason values, that evidence is a verbatim quote, the 'only what the tool result contains' constraint, and the one-extra-LLM-call cost. No contradiction with annotations.

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

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

Front-loaded with the core purpose, then mechanics, return contract, usage guidance, and cost tradeoff in a tight sequence. Roughly 110 words but every sentence carries distinct information — the return shapes, refusal reasons, and cost comparison all earn their place.

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

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

There is no output schema, so the description correctly shoulders the burden of explaining return values — and it does so exhaustively for both success and refusal paths, including the full refusal_reason enum. For a high-complexity tool (routing across 5,706 tools), the decision-relevant context (grounded vs. casual, cost, refusal semantics) is fully covered.

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

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

Schema description coverage is 100% — all six parameters (question plus five aliases) are documented in the schema itself. The description doesn't add parameter-level meaning beyond that, so the baseline 3 applies. The routing mention ('fills arguments') is behavioral context, not parameter semantics.

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 differentiator ('Hallucination-resistant answer mode for high-stakes reads') and details the extraction mechanism: it routes like ask_pipeworx but answers using ONLY what the tool result contains. This clearly distinguishes it from the sibling ask_pipeworx and other research tools without needing to open any schemas.

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

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

Explicit when-to-use is given ('whenever an answer will be quoted, cited, or acted on... financial verdicts, legal claims, medical lookups, public statements') and when-not-to-use with the named alternative ('Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups'). Nothing is left to inference.

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?

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false; description adds substantial behavioral context: account requirement, parallel tool routing, gaps[] for unanswered facets (never invented), contradictions[] scan, semantic excerpting (not head-truncated), hop field, citation_uri resolvability, and latency expectations. No contradiction with annotations — description fully complements them.

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

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

Long but information-dense; every sentence adds a new behavioral fact. The most important routing information (account requirement, alternative tool) is front-loaded. Slightly verbose toward the end (citation_uri explanation could be tighter), but no filler.

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

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

Despite no output schema and no nested objects, the description compensates thoroughly: explains return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop), failure mode (empty gaps[]), auth requirement, latency, and depth semantics. An agent has everything needed to decide whether and how to call this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining what depth levels actually do behaviorally ('standard' re-angles unanswered gaps; 'thorough' chases leads) and clarifying that broad/multi-part questions are fine. This elevates it above baseline.

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

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

Description states a specific verb ('research') and resource ('Pipeworx's 1493 STRUCTURED data sources across 5,706 tools') and distinguishes itself from open-web search and siblings. It clearly positions deep_research as the multi-source, multi-hop research tool versus ask_pipeworx for single lookups.

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

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

Explicitly names when to use deep_research (broad/multi-part questions over structured data) and when to use ask_pipeworx instead (single lookup, breaking/current-news topics, not signed in). Also contrasts with open-web search. Gives concrete examples and exclusions.

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

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

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?

The description goes far beyond the annotations, disclosing concrete behavioral traits: the claim_token mechanism for follow-up reads, the daily digest review, the 5-per-identifier-per-day rate limit, and the fact that it's free and doesn't count against quota. It also notes not to paste user prompts. No contradiction with annotations exists.

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

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

The description is a single dense paragraph, but every sentence contributes substantive guidance: use cases, exclusions, token mechanics, rate limits, and reporting etiquette. It's slightly longer than necessary, but the detail is justified given the tool's nuanced usage. The purpose is front-loaded in the first sentence.

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 (4 params, nested context object, no output schema), the description covers all necessary aspects: what to report, when to report, where not to report, how to check on a report, rate limits, and behavioral expectations. There is no missing critical information for an agent to use this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds extra semantics beyond schema: it explains the claim_token usage pattern with a concrete call example ('pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies that passing only claim_token reads a previous report. It also explains the type enum options in context, adding value beyond the schema's phrasing.

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, action-oriented purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools like ask_pipeworx or deep_research by framing it as a feedback reporting channel, not a knowledge/query tool. The scope is explicit: feedback about Pipeworx tools/packs only.

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

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

The description provides explicit when-to-use scenarios: '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 a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage guidance with named alternatives and boundaries.

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?

Even though readOnlyHint and idempotentHint already signal a safe read operation, the description goes far beyond annotations: it details response safety fields, explains all compatibility codes, clarifies that unclassified legs are never paired, and exposes skipped comparison counters and temporal alignment semantics. It also warns that returned pairs can carry non-empty compatibility warnings. This is rich behavioral disclosure that materially helps an agent interpret results correctly.

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 densely informative, and it is well-structured with clear labels ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS'). The most important purpose and disclaimer are front-loaded, and the compatibility code inventory is grouped logically. Some repetition exists (e.g., the caveat that pre-mapped pairings may be unverified appears twice), so it is slightly less concise than ideal, but every major section 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?

Given there is no output schema, the description carries full responsibility for explaining return semantics, and it does so thoroughly: it covers leg-by-leg prices, matched spreads expressed in percentage points, compatibility warnings, skipped/unclassified categories, temporal alignment, and counters. With three optional parameters and no required fields, the tool is also credential-free and side-effect-free, so nothing an agent needs to call or interpret it is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds meaning by explaining the relationship between the parameters: topic is a pre-mapped shortcut, the two explicit parameters override the topic-mapped side, and they exist for custom pairings. It also gives concrete examples ('fed', 'KXFED-26OCT', 'fed-decision-in-june-825') that clarify expected formats. This exceeds the baseline but does not heavily elaborate on all parameter edge cases.

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

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

The opening sentence states a specific resource ('Cross-venue spread between Kalshi and Polymarket for the same resolving question') and a precise computation ('the two venues sometimes price the same outcome 2-25pp apart'). It clearly distinguishes this tool from the broader sibling set by emphasizing cross-venue comparison rather than single-venue analysis, and the two modes are explicitly enumerated. This is a specific, differentiated 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 gives clear context for when to use the tool: when comparing the same resolving question across Kalshi and Polymarket, and explains the two modes with explicit instructions for when to use the pre-mapped topics versus explicit tickers/slugs. It also warns against over-trusting pre-mapped results ('pre-mapped ≠ tradeable') and explains that most topics return compatibility warnings. However, it does not explicitly name alternative sibling tools or state when one of those should be preferred, so it lacks full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, 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 readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds value by explaining that each call cascades through several internal lookups (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), and that identifiers are labelled with source and unresolved ones are listed explicitly. No contradictions with annotations exist.

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

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

The description is dense and front-loaded with examples of natural language queries. While comprehensive, it contains some redundancy (e.g., multiple examples for company type) that could be trimmed slightly. Overall, it is well-structured and informative without excessive 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 (multiple data sources, graceful degradation) and no output schema, the description covers essential behavior including what identifiers are returned, how failures are reported, and the internal cascade logic. It could mention pagination or response size limits, but for a lookup tool of this nature, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the input schema already documents both parameters adequately. The description enriches by explaining how the 'value' parameter can be a ticker, CIK, ISIN, or name for company type, and brand or generic name for drug type. This adds context but is not critical since the schema already provides clear descriptions.

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

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

The description clearly states that the tool resolves user-spoken names to canonical/official identifiers. It provides specific examples and lists supported entity types (company, drug), distinguishing it from siblings like compare_entities or entity_profile by explicitly stating 'use FIRST whenever you have a name but need an ID'.

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 instructs when to use this tool ('whenever you have a name but need an ID') and provides context on what types of queries it handles. It also mentions graceful degradation when external services are unavailable, which helps an agent decide between this and alternative lookup tools.

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

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

Annotations already declare readOnlyHint, 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?

Goes well beyond the readOnly/openWorld/idempotent annotations by explaining the dual pipeline (SEC EDGAR fast path vs. grounded fallback), the distinct meaning of 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source exists), and the return structure. This is critical behavioral context an agent needs to avoid misinterpreting 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 long but every sentence earns its place: example phrasings, usage scope, routing logic, return values, and caveats for two special verdicts. It is front-loaded with the most actionable info and structured logically.

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 fully covers return values (verdict, actual value with citation, reasoning) and explains edge statuses (could_not_verify, unsupported) including error details. The description is self-sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, and both parameters are already well documented. The tool description does not add any parameter-specific meaning beyond the schema; it merely restates claim examples that are already in the schema. 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 identifies the tool as natural-language claim verification against authoritative sources, with a specific verb ('validate/verify') and resource. It includes concrete example phrasings and distinguishes itself from generic Q&A tools like ask_pipeworx by focusing on claim verification with verdict outcomes.

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 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use trigger. However, it does not name alternative tools or explicitly state when not to use this tool, so it misses the 'when-not/alternatives' part of a 5.

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