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 description adds useful behavior beyond the annotations: it routes across 5,798 tools, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. It also clarifies coverage of current and historical data. The annotations already declare read-only, idempotent, and non-destructive behavior, and the description does not contradict them.

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

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

The description is front-loaded with a strong directive and includes useful examples and domain lists. However, it is lengthy, and the ending is structurally garbled: 'if you need broad/multi-part question...' appears unfinished and the following sentence reads awkwardly. The density is mostly justified, but the imperfect closing keeps it from being a model of concise structure.

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 broad routing tool with no output schema, the description does well to explain return behavior, coverage, and example use cases. However, it lacks explicit distinction from the similarly named ask_pipeworx_beta and ask_pipeworx_grounded siblings, and the incomplete multi-part-question guidance leaves a meaningful gap. This is adequate but not fully complete for an agent deciding among many related tools.

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 schema already fully documents the 'question' parameter and its aliases. The description's examples illustrate query phrasing and its 'fills arguments' note implies the agent only needs to provide the natural-language question, adding some context. This matches the baseline of 3 expected when the schema carries the parameter-documentation load.

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

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

The description clearly states a specific verb and resource: it routes a natural-language question to relevant data tools and returns structured answers with stable citation URIs. It also enumerates concrete domains, making the tool's function easy to understand. However, it does not differentiate among the sibling variants ask_pipeworx_beta and ask_pipeworx_grounded, so it stops short of full sibling distinction.

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 usage guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions' with examples and trigger phrases. It also says to use it even when web search could answer. It does not explicitly name alternatives like deep_research or the ask_pipeworx variants, and the 'broad/multi-part question...' sentence is incomplete, so exclusions are only partially stated.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It does: live candidate routing may be enabled during tests, no candidate is currently active, and there is no fallback — it is a full working router. This materially informs an agent about behavior that annotations cannot capture.

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 identity, then provides current state, usage, and fallback behavior in short, information-dense sentences. Every sentence earns its place, including the specific date that explains why the current behavior matches the stable router. No filler or redundant restatement of the tool name.

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 still communicates response-shape parity with ask_pipeworx, which is the key missing piece. It covers current runtime state, usage equivalence, experimental nature, and failure semantics with no fallback. An agent has enough to decide when to invoke it and what to expect.

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

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

Schema description coverage is 100%, so the structured schema already documents the parameters. The description adds that arguments are identical to ask_pipeworx and that the tool is used the same way, but it does not add new semantic detail about each parameter. Baseline 3 applies because the schema carries 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 states a specific object scope: it is the beta version of ask_pipeworx, an identical universal router over 5,798 tools with the same arguments and response shape. It clearly distinguishes itself from the stable ask_pipeworx sibling by highlighting its experimental routing edge. The purpose is not merely restated; it is concrete and actionable.

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

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

The description explicitly tells the agent to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router. It also clarifies the current state: no candidate is active, so it matches ask_pipeworx exactly. It could be stronger by naming explicit exclusion cases for stable routing, but the primary decision logic is clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses concrete behavioral details: it only uses tool-result content, returns evidence as a verbatim quote, may refuse with specific refusal_reason values, and costs one extra LLM call. This is rich behavioral context that cannot be inferred from annotations.

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

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

The description is dense but every sentence earns its place: it explains the mechanism, return shape, refusal reasons, when to use, and cost trade-off. It front-loads the core purpose and does not repeat schema information. No wasted words.

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

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

Despite no output schema, the description fully specifies both success and refusal return shapes, key behavioral guarantees, usage context, and comparison to the sibling. The tool is complex (routing among thousands of tools), but the description gives an agent everything needed 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?

Schema description coverage is 100%, so the schema already fully documents the 'question' parameter and its aliases. The description does not add parameter-level semantics beyond noting that the tool 'fills arguments' generically, which is not needed given the schema. Baseline 3 applies.

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

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

The description clearly states a specific purpose: a hallucination-resistant answer mode that extracts answers using only the tool result content. It distinguishes itself from ask_pipeworx by naming the same routing but the grounded extraction behavior. The verb 'EXTRACTS' and resource context are precise and unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and provides the alternative: 'prefer ask_pipeworx for casual lookups.' It also mentions the extra LLM call cost, helping the agent make a trade-off decision.

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 already cover read-only/idempotent/non-destructive behavior, so the bar is lower. The description adds substantial value: explains latency (15-60s, up to ~90s for thorough), gap handling (explicit gaps[] never invented), contradiction scanning, semantic excerpting of large records, citation behavior (stable pipeworx:// references, always fetchable), and account/depth requirements.

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

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

The description is information-dense but somewhat sprawling for an initial tone (ACCOUNT REQUIRED, depth tier pricing, internal implementation details like the 5,798 tools). The sentences run long and mix operational details (latency, follow-up passes) with usage guidance. It earns its place mostly, but a clearer top-line 'what + when' structure would improve it.

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

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

Despite no output schema, the description thoroughly explains the return shape (findings packet, verbatim evidence + confidence + source + fetched_at, citations, gaps[], contradictions[]) and the failure modes (gaps never invented, latency expectations, account tier gate). An agent has everything it needs to decide when to call this and what to expect back.

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 both parameters are documented. The description adds context by explaining what 'depth' values actually do (quick=3 facets single-hop, standard=3 with gap recovery, thorough=6 paid with iterative hop) and clarifies that the question parameter accepts natural language, multi-part questions. Justification referencing the enums' behavioral implications goes beyond schema.

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

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

The description clearly identifies deep_research as a grounded multi-source research tool across Pipeworx's 1517 structured data sources, explicitly distinguishing it from open-web search and naming its sibling ask_pipeworx as the alternative. It specifies what it does — decomposes questions, routes facets in parallel, returns a findings packet — and provides example use cases.

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 this tool (broad/multi-part questions over structured data) and when not to (single lookup → use ask_pipeworx instead). Also gives clear account requirements, noting that unsigned users should use ask_pipeworx. It even differentiates between depths (quick/standard/thorough) and what each provides.

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?

Annotations already mark the tool read-only, idempotent, and non-destructive; the description adds substantial behavioral context beyond that: one parallel fan-out, USPTO soft-fail timing, empty FDA sections being expected rather than errors, and sources_used/sources_failed semantics. This is rich, non-contradictory transparency.

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

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

The description is long but densely informative; it front-loads trigger examples and the key usage rule before the field-by-field breakdown. Every sentence adds operational value, and the structure suits the tool's inherent 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, the description fully compensates by enumerating all return sections, including failure modes, empty-section semantics, and the resolved:false private-company case. It covers input, output, edge cases, and source reliability, so an agent can invoke it correctly without external assumptions.

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

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

Schema coverage is 100%, and the description goes further by explaining concrete accepted shapes (ticker, zero-padded CIK, name), name resolution via SEC EDGAR, and that type values are interchangeable. It also uses real examples, adding practical meaning the schema alone does not convey.

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

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

The description opens with concrete user phrasings and states a specific verb+resource: "full cross-source profile of a US public company in ONE parallel call." It distinguishes itself from sibling single-pack lookups and clearly enumerates the data sources aggregated.

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

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

Explicit guidance is present: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also clarifies alternative input forms and describes expected behavior for private companies, so an agent knows when this tool applies and what to expect.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, lowering the bar. The description goes well beyond them, disclosing that matching is keyword/word-overlap based rather than a shared resolution source (pairing_unverified set in EITHER mode), that spreads are gross of Kalshi fees which the tool does not model, that null temporal_alignment means 'could not be computed' not 'aligned,' and that unknown-metric legs are never paired. This is exactly the kind of behavioral context an agent needs to avoid over-trusting output.

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 earns most of its length: with no output schema it must document response shape, safety codes, fee treatment, and skipped-leg semantics in prose. Section markers (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) impose structure and the core purpose is front-loaded. Minor redundancy exists — the ten topic shortcuts are repeated verbatim in the schema description — and the code-by-code enumeration is dense, but nothing is filler.

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

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

For a two-venue, two-mode, no-output-schema tool with subtle failure modes, the description is remarkably complete: it covers input modes, response shape (raw probabilities, top_spreads_pp, skipped_unclassified, low_confidence_pairs), all compatibility codes, temporal-alignment semantics including the null meaning, fee-schedule non-modeling, and per-pair flags. An agent has everything needed to invoke it correctly and interpret its output conservatively.

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 and the schema already documents all three optional parameters. The description adds genuine value beyond the schema: the topic shortcuts auto-fetch the matching event on each venue, explicit ticker/slug override the topic-mapped side, and both modes run the identical token-overlap matcher with the same disclosures. The override relationship and mode-equivalence are not recoverable from the schema alone.

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

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

Opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This distinguishes it from siblings like polymarket_arbitrage and polymarket_edges, which target different comparison/edge patterns. The scope constraint ('same resolving question') and the 2-25pp magnitude detail give the agent a concrete picture of what the tool computes.

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?

TWO MODES are explicitly contrasted with the conditions that select each: topic shortcuts for pre-mapped macro pairs, explicit ticker+slug for custom pairings, and the override semantics between them are stated. It also gives a when-NOT: 'pre-mapped ≠ tradeable' and warns most topics return compatibility_warning today. However, it never names sibling alternatives (e.g., when to use polymarket_edges or polymarket_fill_risk instead), so cross-tool routing 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?

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?

Adds substantial behavioral context beyond annotations: graceful degradation when enrichment sources fail, internal cascading lookups, behavior on ambiguous matches (returns figi_candidates rather than asserting), explicit unresolved listing, and source labeling on identifiers. Annotations already declare read-only/idempotent, and the description enriches that with real edge-case 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 and dense, but it is front-loaded with trigger phrases and organized by supported type. Each section adds non-obvious operational detail. It could be tightened, especially the bond/figi_candidates passage, but the length is largely justified by the tool's complexity.

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

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

Despite lacking an output schema, the description covers what agents need to call the tool correctly: trigger phrasing, type selection, accepted input formats, ambiguous-match behavior, unresolved-identifier policy, source attribution, and degradation guarantees. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds vital semantics: the difference between company and drug, accepted identifier formats, ISIN-to-legal-entity behavior, and the crucial warning to pass only the entity name, with a concrete bond example showing why trailing security-class words break lookup. This meaningfully exceeds the schema's brief 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?

States a clear verb and resource: resolve a user-spoken name into canonical identifiers. The natural-language trigger examples and supported entity types make the purpose immediately recognizable and distinct from sibling tools like entity_profile or compare_entities, since this tool focuses on lookup/ID resolution.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which is strong usage guidance. It also clarifies what inputs are accepted for each type. It does not explicitly name sibling alternatives or conditional exclusions, so it stops short of full when-not-to-use guidance.

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

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

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