onthisday

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: the default model is free, and passing `_apiKey` means 'you pay Anthropic directly,' disclosing cost implications. It also clarifies the return payload. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core function and output, followed by pricing/alternative details and use cases. Every sentence provides necessary information without wordiness. It's an exemplary compact description.

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 appropriately includes return format: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also covers default behavior, optional key, and typical use cases. Minor gaps like error handling or scoring methodology prevent a 5, but it is quite complete for a read-only probe tool with strong annotations.

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

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

Schema description coverage is 100%, so all four parameters have clear documentation. The description adds extra meaning by explaining the default model and the conditional need for `_apiKey` only when 'anthropic' is in models, which the schema's per-parameter description doesn't fully convey. This elevates it above the baseline of 3.

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

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

The description opens with a specific verb+resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence by emphasizing per-model visibility scoring. It also provides concrete output structure (score, confidence, signals) and 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?

The description states 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' giving clear contexts for when to use it. It also explains the default vs. optional Anthropic probe, which helps decide whether to bring an API key. However, it does not explicitly name alternatives or when not to use, so it falls slightly 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: it routes to the appropriate tool, fills arguments, returns a structured answer with citation URIs, works on every tier, and makes one fast call. This enriches the safety profile without contradicting annotations.

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

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

The description is long but densely informative, with a clear hierarchical structure: primary use case, routing behavior, trigger phrases, examples, and when to escalate. Some redundancy exists (e.g., 'START HERE' and 'default entry point' say similar things), but every sentence contributes actionable guidance.

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

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

Despite no output schema, the description explains what the user gets back (structured answer with stable citation URIs) and covers broad applicability, edge cases (breaking news), and escalation paths. For a tool of this complexity, it is remarkably 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% and all parameters are well-described aliases of a single 'question' field. The description adds value with natural-language examples and the clarification that the question can be any factual request, including the alias list. It doesn't provide deeper syntax detail but the schema already handles that, so a 4 is appropriate.

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

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

The description clearly states the tool's function: it answers factual questions by routing to one of 5,529 tools across verified sources and returns structured answers with citation URIs. It explicitly contrasts with siblings like ask_pipeworx_grounded and deep_research, making the primary use case unmistakable.

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

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

The description gives explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research). It also lists trigger phrases and examples, leaving no ambiguity about when to use this tool versus others.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description adds valuable behavioral context: it is a full working router, currently no candidate is active, and it is the experimental edge. It transparently explains the fallback behavior ('Falls back to nothing') and the purpose of the beta, enriching the agent's understanding of runtime 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 moderately long but efficient; each sentence adds meaningful context (beta status, identity of router, current state, usage direction, fallback). It is front-loaded with the most important information and does not waste words, though it could be slightly trimmed without losing value.

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

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

The description fully covers the tool's role, relationship to ask_pipeworx, current operational state, and fallback behavior. Since it explicitly states the response shape is identical to ask_pipeworx, the absence of an output schema is not an issue. The description is complete for an AI agent deciding to invoke this tool.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters (question plus five aliases). The description adds minimal parameter-specific detail beyond referencing 'same arguments,' 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 identifies the tool as a beta version of ask_pipeworx with an identical universal router (same 5,529 tools, arguments, response shape). It distinguishes itself from the stable ask_pipeworx by mentioning candidate routing improvements, making the purpose specific and unambiguous.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing,' providing a clear usage scenario. It also notes that results are compared against the stable router, implying the alternative (ask_pipeworx). It doesn't explicitly list when not to use it, which costs one point, but the guidance is otherwise 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant detail about refusal behavior, return format, and the extra LLM call cost beyond what annotations convey. The refusal_reason enum and evidence-quote mechanism add behavioral transparency. It doesn't explicitly mention idempotency or open-world behavior, but those are already covered by annotations; the description adds unique context about failure modes and output guarantees.

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-loads the core purpose, and packs every clause with useful information. It clearly distinguishes this tool from the sibling and communicates the trade-off, return contract, refusal reasons, and use cases without any filler or repetition of structured data.

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-question-parameter tool with rich annotations, the description is fully complete: it explains the success/refusal responses in detail, explicit usage guidance, and cost trade-off. No output schema exists, so the description's detailed return contract fills that gap. The sibling differentiation further completes the contextual picture.

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%, with all six parameters documented as aliases for 'question.' The description correctly refers to natural language input but does not add any details beyond the schema's aliases and type. Baseline 3 is appropriate since the schema fully covers parameter semantics.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads, distinguishing it from the sibling ask_pipeworx. It uses specific language like 'EXTRACTS the answer using ONLY what the tool result contains' and details the return contract, making the purpose unmistakable.

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

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

Explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and gives concrete examples (financial verdicts, legal claims, medical lookups). It also provides an exclusion: 'prefer ask_pipeworx for casual lookups' and notes the extra cost, guiding when not 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?

The description extensively discloses behaviors beyond annotations: resolver contract (market_match_confidence, suggestions), safety short-circuits for low-confidence matches, closed-market handling, wide-spread tradeability, cancellation-rule parsing, and news fallback fields. This goes far beyond the read-only/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?

The description is long but well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose in the first sentence and every subsequent section adds operational detail an agent needs. While verbose, the density of unique value justifies the 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?

For a complex tool with no output schema, the description covers all critical facets: input formats, classification taxonomy, parallel fan-out, response shape with key fields, resolver confidence contract, parent-event extraction, news fallback handling, safety short-circuits, liquidity warnings, and resolution-rule risk. An agent has sufficient context 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 schema descriptions already cover all three parameters at 100% coverage. The description adds concrete examples for the market parameter (slug, URL, question text), explains default depth behavior, and clarifies include_raw's impact on response size. This adds meaningful context without being redundant.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' clearly stating the verb, resource, and one-call scope. It distinguishes from sibling tools like deep_research or polymarket_arbitrage by specifying the Polymarket bet research niche and the fan-out to category-specific data packs.

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 use-case phrases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives fan-out examples per category (BTC bet, Fed bet, etc.), clarifying when each classifier applies. However, it does not name alternatives or exclusions, so it is clear but not fully explicit about when not to use.

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

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

Beyond the readOnlyHint and idempotent annotations, the description reveals key behaviors: it pulls specific metrics (10-K revenue, net income, cash, long-term debt for companies; FAERS, FDA approval, trial counts for drugs), handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. This is rich, non-obvious behavioral detail.

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

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

The description is longer than average, but every sentence adds operational value—trigger phrases, data-source details, fiscal-year handling, sorting, and output specifics. It is front-loaded with the most actionable guidance ('ALWAYS PREFER...'), though slightly dense; a bit of trimming could improve scannability without losing info.

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 compensates by explaining what the response contains (paired data + citation URIs) and how results are ordered. It also covers edge cases (fiscal-year differences) and explicitly contrasts with the sequential-lookup alternative, making the tool fully self-contained for an agent to use correctly.

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

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

Although the schema already documents both parameters with 100% coverage, the description adds substantial meaning: it maps 'type' values to distinct data sources and metrics, and elaborates on the 'values' format with examples (tickers vs drug names) and constraints (2–5 items). This goes well 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 uses a specific verb ('compare') and names the exact resources ('2–5 companies or drugs') in a side-by-side parallel call. It clearly distinguishes itself from the sibling tool 'entity_profile' by emphasizing multi-entity comparison in a single call, making the purpose unmistakable.

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

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

It explicitly states when to use this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides concrete trigger phrases ('X vs Y', 'rank these companies') and clarifies the distinction between company and drug types, giving clear context for selection versus 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: account/payment requirements, decomposition and parallel routing, latency expectations ('15-60s', 'up to ~90s'), return packet contents (verbatim evidence + confidence + source + fetched_at + citation_uri), the gaps[] mechanism (never invented), contradictions[] scanning for certain depths, and semantic excerpting of large records. It also explains the citation_uri is 'present only when the source emits one that resources/read can actually serve', adding trust/practical details. No annotation contradiction 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 long but every section carries unique, non-redundant information. It is front-loaded with the most critical caveat (account required) and then flows logically. However, it is a dense paragraph without sub-structure; a bulleted list or clear section breaks could improve scannability. Still, no sentence is wasted, and the length is justified by the tool's complexity.

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

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

Given that there is no output schema, the description fully documents the return packet (findings with verbatim evidence, confidence, source, fetched_at, citation_uri, hop, gaps[], contradictions[]) and explains behavior under different depth settings. It also covers authentication, latency, fallback to ask_pipeworx, and limitations for current-event topics. This is comprehensive and leaves no major unknown for an agent deciding whether and how to invoke the tool.

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

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

Although the input schema has 100% coverage and already explains both params, the description adds substantial meaning: it clarifies that the question can be 'broad/multi-part', that decomposition is the point, and provides a full breakdown of the depth enum including what each level does (quick=3 facets, standard=gap recovery + contradictions scan, thorough=paid iterative hop + contradictions scan). This goes well beyond the schema's own descriptions and helps the agent select appropriate depth.

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: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that 'decomposes your question into focused facets' and routes to tools in parallel. It explicitly distinguishes itself from open-web search ('this is NOT open-web search') and from sibling tools by naming ask_pipeworx and defining when that alternative is better. The verb+resource+scope are specific and unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also gives a clear exclusion: 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. Additionally, it covers prerequisite conditions (account required, paid tier for depth:'thorough') and states when deep_research is not suitable ('returns mostly empty gaps[] when the topic isn't in the structured catalog').

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

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

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral context: it returns top-N tools with names, descriptions, and full input schemas including curated examples, and that results are ready to call directly without a second lookup. This explains the tool's meta behavior and output richness clearly.

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

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

The description is reasonably concise and front-loaded with the core purpose. The long list of domains in the second sentence adds some bulk but serves as concrete examples of use cases. Overall, it is well-structured without unnecessary 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?

With no output schema, the description sufficiently explains what the tool returns (names, descriptions, full schemas, examples) and when to use it first among many tools. It addresses the key aspects an agent needs to understand the tool's role and output, making it complete for its complexity.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters including query aliases and limit. The description adds a brief mention of free-form task descriptions but doesn't materially enhance parameter semantics beyond what the schema already provides, 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 clearly states 'Find tools by describing the data or task' with a specific verb and resource (tools). It distinguishes itself from siblings by emphasizing discovery/browsing of available tools, as opposed to tools that perform analysis or access specific data.

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 context: 'Use when you need to browse...' and 'Call this FIRST when you have many tools available and want to see the option set.' It does not explicitly name exclusions or alternatives, but the guidance is clear enough for an agent to decide when this tool is appropriate.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses substantial behavioral details: the tool fans out across multiple sources in parallel, returns specific fields (cik, filings, fundamentals, patents, news, LEI), includes 'up to 5' filings with URIs, and notes soft-fail behavior for the USPTO API sunset and a GDELT→GNews fallback. This adds significant context beyond structured fields.

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

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

The description is appropriately detailed for a complex tool yet tightly structured: front-loaded with example queries, then purpose, preference rule, fan-out details in a semicolon-separated list, and input format note. No wasted sentences; every part contributes.

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 must cover return values, which it does thoroughly: it lists all returned components (cik, recent_filings, fundamentals, patents, news, LEI) and their formats. Input constraints and edge cases (e.g., API sunset soft-fail) are also covered, making the description self-sufficient.

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

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

The input schema already has 100% description coverage with examples for both parameters. The description adds reinforcing context by explicitly giving valid ticker and zero-padded CIK examples and repeating the unsupported-names constraint, which strengthens understanding even though the schema already covers it.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call' and includes specific example queries. It distinguishes itself from single-pack SEC/XBRL/news lookups by saying 'ALWAYS PREFER over chaining' when a holistic view is requested.

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

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

The description provides explicit when-to-use guidance with example queries ('Tell me about X', 'research Acme') and states when not to use it: 'names not supported (use resolve_entity first if you only have a name)'. It also identifies the alternative approach it should replace, giving clear usage context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds context about clearing sensitive data but does not elaborate on return behavior, missing-key handling, or irreversibility, which is acceptable given 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?

Three short sentences: purpose, usage conditions, and related tools. Every sentence earns its place, with the action front-loaded. No redundant phrasing.

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 one-parameter tool with destructive and idempotent annotations, the description covers purpose, usage, and related tools. No output schema exists, but the description sufficiently frames the operation.

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% for the single 'key' parameter, which is already documented as 'Memory key to delete'. The description adds no new parameter-level meaning beyond what the schema provides, so 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 begins with a specific verb ('Delete') and resource ('previously stored memory') plus method ('by key'), making the purpose unmistakable. It clearly distinguishes from siblings like remember (store) and recall (retrieve).

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 conditions ('context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with remember/recall. It lacks when-not-to-use or alternative tools, but clear context is given.

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. Description adds behavioral detail: fetches the page, extracts title/description/key links, and outputs a single text blob ready for site-root. 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 three sentences with a clear action first, process second, and use cases third. It is well-structured and each sentence adds value, though the use-case list could be seen as slightly expansive.

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

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

For a simple tool with 2 parameters, the description adequately covers purpose, process, output format, and use cases. Since no output schema exists, the description's mention of a text blob fills that gap effectively.

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 parameters are fully documented in the schema. The description does not add extra parameter context beyond what the schema provides, matching the baseline of 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 explicitly states the tool generates a production-ready llms.txt file for any URL, with a clear verb+resource. It also describes the process (fetches, extracts, emits markdown) and distinguishes from sibling tools by focusing on file generation rather than just auditing.

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 usage context with 'Useful for' scenarios including client indexing, personal projects, and competitor auditing. However, it does not explicitly mention when not to use it or alternative tools like scan_competitor_ai_presence.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive, so the bar is lower. The description adds behavioral context by specifying the output includes names, birth years, and biographical details, which goes beyond the annotations and helps the agent understand what to expect.

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 only two sentences, front-loaded with the purpose and then the required inputs. Every sentence adds information, and there is no redundant or extraneous text.

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

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

For a simple two-parameter tool with a rich output schema and strong annotations, the description is adequately complete. It covers what the tool does, what inputs are needed, and what users can expect in the output, making it sufficient for a straightforward query tool.

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

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

Schema coverage is 100% with descriptive property definitions for month and day. The description restates the same ranges (1-12, 1-31) without adding new semantic value beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states the tool finds notable people born on a specific date, using the verb 'Find' with a specific resource. It distinguishes from sibling tools like get_deaths and get_events by focusing on births and listing the specific return data (names, birth years, biological details).

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 usage context: the tool is for finding births on a specific date, requiring month and day. It does not explicitly compare to alternatives or state exclusions, but the context is sufficiently clear to guide appropriate use.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the scope 'notable people' and mentions return content, but with an output schema present, this adds minimal behavioral context beyond what annotations and schema 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 two concise sentences, front-loaded with the core purpose, with 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?

For a simple two-parameter lookup with comprehensive annotations and an output schema, the description adequately covers the tool's purpose and input expectations. No additional context is necessary.

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 both day and month described in the input schema. The description reinforces the format (1-12, 1-31) but does not add 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 uses the specific verb 'Find' and clearly identifies the resource as 'notable people who died on a specific date.' This distinguishes it from sibling tools like get_births and get_events by focusing on death and date.

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 use (providing a month and day to get deaths), but does not explicitly mention alternatives or when not to use this tool. It implies usage by stating the required inputs.

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 destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return content ('event descriptions, years, and details'), which goes beyond the annotations and gives the agent a clearer picture of the tool's output 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 two short sentences, front-loaded with the core action and then detailing parameters and returns. Every word earns its place with no redundancy or filler.

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

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

For a simple two-parameter tool with a well-defined input schema and an output schema present, the description provides enough context: what it does, what parameters are needed, and what it returns. It does not mention potential limitations (e.g., pagination, date range boundaries), but given the tool's simplicity and annotation coverage, this is not a significant gap.

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 with descriptions for both 'month' and 'day', including their ranges. The description's mention of 'month (1-12) and day (1-31)' largely repeats the schema, adding no new semantic depth, 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 a specific verb ('Search') and resource ('historical events') with a date qualifier, making the tool's purpose unambiguous. It does not explicitly differentiate from sibling tools like get_births or get_deaths, but the term 'historical events' implies a broader scope, earning a 4 rather than a 5.

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 the tool: for searching historical events on a specific date, with required month and day parameters. However, it provides no explicit guidance on when not to use it or how it relates to alternative sibling tools such as get_births or get_deaths, so the context is clear but exclusions/alternatives are missing.

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

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

The description discloses the return fields (id, type, params, created_at, last_fired_at, fire_count) and the scope ('caller's active subscriptions'). With annotations already indicating readOnly, idempotent, and non-destructive behavior, the description adds useful context about the response and scope without contradicting annotations.

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

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

Two sentences, front-loaded with the primary action and return value list. Every sentence earns its place: the first defines the operation and output, the second gives practical usage context. No filler or redundancy.

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

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

The description is complete for this simple tool: it states the return shape, clarifies the default scope, and provides usage guidance. The sibling tools include subscribe/unsubscribe, making the described use case meaningful. No output schema is needed since the description enumerates fields.

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

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

The input schema has 100% coverage for the single parameter, including its own description. The tool description adds minimal extra meaning beyond the schema, but it does imply that 'active' is the default and that include_inactive changes that, which is helpful 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 clearly states it lists the caller's active subscriptions, naming the resource and action. It also distinguishes itself by specifying the return fields and mentioning use cases relative to subscribe/unsubscribe ('before adding more', 'find an id to cancel').

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 given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This defines clear contexts for use, though it does not explicitly state when not to use it or mention alternatives beyond the implied subscribe/unsubscribe siblings.

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 only say readOnlyHint=false, destructiveHint=false, adding no nuance. The description compensates richly by disclosing rate limits (5 per identifier per day), free/quota-free status, the claim_token workflow, and that 'the team reads digests daily and signal directly affects roadmap.' This is actionable behavioral context beyond the structured 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?

Though longer than average, every sentence carries a distinct, necessary piece of information: purpose, use cases, exclusions, token mechanics, and rate limits. The structure is logical and front-loaded; no filler or repetition of schema text.

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

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

For a 4-parameter tool with no output schema, the description covers everything an agent needs: what to report, when to use it, how to scope feedback, how to follow up with a claim_token, and operational constraints (rate limit, quota). It also anticipates the likely confusion about which server's tools are eligible.

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 all parameters. The description adds value for claim_token ('Filing without an account returns a claim_token; pass it back later...') and reiterates the feedback-type categories, but largely reinforces rather than extends the schema. It crosses the baseline 3 by adding a concrete usage pattern for claim_token.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates this feedback tool from sibling research/retrieval tools by enumerating the exact categories it handles (bug, feature, data_gap, praise) and explicitly states what it is not for (other servers' 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?

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: files for non-Pipeworx tools should go to that server instead, and tells users how to identify Pipeworx tools.

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

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

Annotations already establish read-only, idempotent, open-world behavior. The description adds non-obvious traits: derived from CF analytics-engine, no PII, cached 5min-1h, and aggregate format (pack, tool, count). This goes well beyond the structured 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 tightly formatted with a lead sentence, a bulleted 'Useful for' list, and a closing technical note. Each segment conveys distinct value with no filler or redundant restatement.

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 explicitly states what is returned (top tools, top packs, total call volume, aggregated as (pack, tool, count)) and notes the caching behavior. For a one-parameter read-only tool, this fully covers what an agent needs to know.

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 sole parameter (window) is fully described in the schema with enum values, and the description augments it with semantics: shorter windows surface current trends while longer windows show steady-state demand. This adds meaningful interpretive guidance over the raw schema.

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

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

The description opens with a clear statement of what the tool reports ('What other AI agents are calling on Pipeworx right now'), then enumerates the outputs (top tools, top packs, total call volume). This clearly distinguishes it from sibling discovery tools like discover_tools by focusing on live cross-agent usage trends.

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, giving concrete contexts for when to consult this tool (hot data sources, canonical tool confirmation, alignment check). It doesn't name alternative tools or state when not to use it, but the 'Useful for' list effectively communicates when it applies.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses many behavioral details: the >3pp threshold for signal emission, the ≥0.30 Jaccard similarity anchor for cross-event pairs, the placeholder filter (>20% returns null), and the fill check logic (realizable_edge_pp ≤ 0 means do not trade). It also explicitly warns about false positives from last-trade only overrounds. This is exemplary transparency; nothing contradicts the annotations.

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

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

The description is long but every sentence carries meaningful information. It is front-loaded with the core purpose, then logically structured into mode explanations, semantic anchor, partition filter, response format, and fill check. Use of labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) makes it easy to parse. No redundant or filler content.

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

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

With no output schema, the description fully explains the return structure (opportunities[] with fields, partition_check in event mode) and notes edge cases (null arb signal for excessive placeholders). It also explains the meaning of key output fields (gap_pp, realizable_edge_pp) and provides a safety check. It even directs to a related tool for custom sizing, rounding out the operational context.

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

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

Even though the schema already describes both parameters (event and topic), the description adds substantial semantics: examples of valid slugs ('fed-decision-may-2026'), full URL acceptance, the distinction between single-event vs cross-event scanning, and the kind of seed question expected for topic mode. This far exceeds the schema's basic descriptions and helps the agent construct correct inputs.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's function from siblings like polymarket_edges or polymarket_fill_risk by focusing on arbitrage detection through specific mathematical checks. The three invocation modes (trending_scan, event, topic) further specify the scope and are named explicitly.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also offers mode-specific recommendations ('event (recommended for a specific market)') and points to an alternative tool for a related need: 'For custom sizing use polymarket_fill_risk.' This goes beyond basic usage and helps the agent select the right invocation.

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 readOnly/idempotent annotations, disclosing computation details (model families, slippage adjustments, Kelly caps), response structure (by_segment, diagnostics), limitations (Fed bets unreliable, rare-by-design, gate relaxations), and caching behavior. It also warns about 24h market moves that may negate the edge.

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 wall of text without section breaks, including implementation-specific details like per-sport α values and 'Run 8' gate relaxations that are unlikely to help an agent select or invoke the tool. While information-rich, it is not appropriately structured for quick scanning.

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

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

Despite no output schema, the description fully accounts for all 9 parameters, response top-level structure, diagnostics, and caching. It even explains why Fed bets are excluded and how to interpret empty segments, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains the rationale for slippage_pp default (zero fees but 20-50bp bid/ask), clarifies that min_partition_leg_kelly applies per-leg inside partitions, and describes how tradeable-edge knobs (max_spread_pp, min_liquidity) drop opportunities where edge isn't realizable.

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 also defines the intended use ('what should I bet on today') and distinguishes itself from sibling tools by focusing on Pipeworx-derived edge detection rather than arbitrage, tracking, or fill-risk tools.

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

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

The description gives clear usage context: 'Built for what should I bet on today' and notes that agents discover opportunities without paging hundreds of markets. However, it does not explicitly name alternative tools or state when not to use this tool, 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?

Annotations already mark readOnly/openWorld/idempotent/non-destructive; description adds meaningful behavior: snapshot gaps, TTL limits, signed edge values, decay computed on absolute value, and no intraday data. No contradictions.

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

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

The description is dense but well-structured: purpose, args, response fields, limitations. All-caps field names aid scanning; every sentence contributes necessary operational detail.

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

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

No output schema exists, but description fully explains the tracked/expired/snapshot_dates response fields, including edge cases like gaps and lifespan meaning. Complete enough to 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 already covers both parameters with descriptions, defaults, and clamps (100% coverage). The description restates defaults and introduces 'snapshot family' but does not add substantive semantics beyond schema.

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

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

Description states a specific purpose: edge persistence/decay telemetry answering 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from a current-edges tool like sibling polymarket_edges.

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

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

It implies usage for historical edge analysis with examples (fresh vs 3-week-old edge) and describes data source. It does not explicitly name alternatives or say when not to use, but context is sufficient.

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

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

Beyond annotations (read-only, idempotent, non-destructive), the description discloses rich behavioral detail: it 'walks the ladder', returns specific computed outputs, and highlights risk like 'thin_legs[]' and 'forced_directional_risk naming the legs most likely to strand you unhedged.' No contradiction with annotations.

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

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

The description is lengthy but well-structured with mode labels and a clear progression from purpose to outputs to usage warning. Every sentence earns its place, though it could be tightened with bullet points for 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?

Given no output schema, the description thoroughly enumerates return values for both modes, including edge cases like thin_legs and max_clean_notional_usd. It covers prerequisites, defaults, and risk implications, making the tool self-contained 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?

While schema coverage is 100%, the description adds substantial meaning: it explains mode-specific semantics (market vs event), side auto-detection in basket mode, size_usd interpreted as settlement notional with shares paying $1, and clamping (10–1,000,000). This goes well beyond 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges as signals to precede, making the tool's unique role unmistakable.

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

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

Explicit usage guidance is provided: '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 not capturable on thin books, partial fills create unhedged directional risk), and distinguishes single-market vs basket modes with clear conditions.

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

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

Even with readOnlyHint=true, openWorldHint=true, and idlempotentHint=true in annotations, the description goes far beyond them. It details the exact conditions for compatibility_warning (matched_pairs:0 with skipped_cross_type>0 vs skipped_cross_type:0), explains temporal_alignment's aligned:false meaning spreads are meaningless, and discloses skipped_cross_type/subtype counters. This is exceptional behavioral disclosure.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose and then adds necessary detail. Every sentence contributes something meaningful, but the density is high and could be seen as overwhelming for a casual user. Still, it earns its length for the complexity involved.

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

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

There is no output schema, so the description carries the full burden of explaining the response. It covers the structure (leg-by-leg prices, spread, top_spreads_pp), critical safety fields (compatibility_warning, temporal_alignment), and even the meaning of skipped_cross_type/subtype. For a tool with this many edge cases, the description is remarkably 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 provides 100% coverage with descriptions for all three parameters. The description adds value by explaining the relationship between parameters (explicit ticker/slug override topic-mapped sides), defining the valid topic enum values, and giving concrete examples like 'KXFED-26OCT.' It doesn't deeply explain each parameter's format, but the schema does that; the mode semantics are the added 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 opens with a specific, verb-like resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this tool from siblings like polymarket_arbitrage by focusing on cross-venue comparison and even explains the two modes (topic shortcuts and explicit pairings). This is a precise, non-tautological 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 clear context on when to use the tool: it explains the two modes (topic macro shortcuts vs explicit ticker/slug) and explicitly states expectations, e.g., 'most pre-mapped topics return compatibility_warning today.' It also gives when-not-to-trade guidance via compatibility_warning and temporal_alignment. However, it does not name alternative tools for cases where the spread isn't meaningful, so it misses the '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.

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

Adds valuable context beyond annotations: scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and list behavior when key omitted. Annotations already declare readOnly/idempotent, so description complements them without contradiction.

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

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

Three sentences, front-loaded: purpose first, then usage context, then scoping and relations. Every sentence earns its place 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?

Simple tool with one optional param and no output schema. Description covers purpose, usage, scoping, and sibling relations. Return behavior is implied from 'Retrieve a value' and 'list all saved keys', so no significant gaps.

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

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

Schema coverage is 100% with key description 'Memory key to retrieve (omit to list all keys)'. Description reiterates this omit behavior but adds no new parameter-specific detail, so 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?

Description uses specific verbs 'Retrieve' and 'list' with clear resource ('value previously saved via remember', 'all saved keys'). It distinguishes from siblings by naming remember and forget.

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

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

Explicitly states when to use ('Use to look up context the agent stored earlier...') and provides alternatives ('Pair with remember to save, forget to delete'), giving clear usage 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?

The description explicitly describes a state-changing operation ('Set mark_read:true to flag returned events read') while annotations declare readOnlyHint=true. This direct contradiction warrants a score of 1 per the rubric. The description otherwise adds useful context about the return payload and HTTP alternative.

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 pack the purpose, return payload, filtering, mutation caveat, and alternative access without redundancy. The core action is front-loaded.

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

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

For a read tool with 100% schema coverage and no output schema, the description covers the return payload, filtering, mutation behavior, and polling. It lacks explicit pagination details but is otherwise complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions filtering by type and since and mark_read, but provides no additional meaning beyond the schema's descriptions. The 'sec_8k' example is a minor addition.

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 pulls fired events from the user's subscription feed and returns the most recent alerts with source, citation_uri, and raw payload. It distinguishes from sibling tools by focusing on fired events and the persisted feed, and even provides an alternative HTTP endpoint.

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 a polling use case ('Polls work fine') and explains how mark_read affects subsequent calls. It offers an alternative for scripts/dashboards via an HTTP endpoint but does not explicitly name sibling tools or state when not 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 well beyond the annotations by disclosing the fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO's soft-fail due to PatentsView sunset, and the exact meaning of the 'since' parameter. It also describes the return structure, which is essential since no output schema is provided. 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 front-loaded with use-case phrases, then systematically covers data sources, fallback behavior, date formats, output shape, and alternative tools. Every sentence adds information; there is no fluff or redundancy despite the 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?

For a tool with no output schema, the description fully explains what the tool returns (changes[] grouped by source, total_changes, citation URIs) and covers edge behavior (rate limits, API sunset, soft-fail). It also names the primary alternative, making the tool's scope complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the parameter semantics (ISO date vs. relative shorthand, ticker or CIK) already present in the schema, but adds no genuinely new param-level meaning beyond reinforcing examples already in 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 this is a 'change feed for a company in the last N days/weeks/months' and enumerates the natural language triggers it serves. It also explicitly distinguishes itself from entity_profile, making its purpose unambiguous and differentiating it from a key sibling.

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

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

It provides explicit usage cues ('What's new with X', 'latest on Y') and states when to use entity_profile instead ('when you want the static profile ... regardless of window'). It also explains the tool's parallel fan-out and fallback behavior, giving clear context for choosing it over 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?

Adds important behavioral details beyond annotations: stored as a key-value pair scoped by agent identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. These details are not in the annotations and enhance the agent's understanding of the tool's behavior. No contradiction with annotations.

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

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

Four sentences, front-loaded with the primary action. Each sentence contributes meaningful information (what, when, persistence, pairing with recalls/forget). No filler or redundancy.

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

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

For a simple 2-parameter memory tool with no output schema, the description covers all essential aspects: purpose, usage triggers, persistence semantics, and relationship to recall/forget. Nothing critical 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 covers 100% of parameters with descriptions. The tool description repeats the key-value concept but adds no significant new parameter semantics beyond the schema, 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?

Description opens with 'Save data the agent will need to reuse later', clearly stating the action and resource. It distinguishes from siblings by explicitly pairing with recall and forget, and provides concrete examples of what to store (ticker, address, preference).

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 when you discover something worth carrying forward' with examples. It also clarifies the relationship to sibling tools 'recall' and 'forget', giving clear context for when to use this tool versus 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 read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers, multiple cascading internal lookups, and source labeling for each identifier. 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?

Although the description is long, every section serves a purpose: examples for quick recognition, supported types, resolution details, and fallback behavior. It is front-loaded with the core use case and structured with clear bullets. No filler or redundant repetition of annotations.

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 no output schema, the description explains return values in detail (identifiers, labels, unresolved list, citations). It also covers error/edge cases (degradation, partial resolution) and mentions that it replaces multiple manual lookups, giving the agent full context to invoke correctly. The description is complete given 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?

The input schema already has high coverage (100%) with descriptions for 'type' and 'value'. The description enriches these by providing concrete examples (AAPL, 0000320193, ozempic), explaining the resolution behavior for each type, and clarifying that company input can be ticker, CIK, or name. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names into canonical/official identifiers (CIK, ticker, LEI, FIGI, RxCUI). The verb 'resolve' and resource 'entity' are specific, and the examples ('ticker for', 'CIK for') make the purpose unmistakable. It also distinguishes itself from siblings by noting it is for name-to-ID conversion, unlike entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. It also details supported types and input formats. However, it doesn't explicitly mention when not to use it or name direct sibling alternatives (e.g., entity_profile for broader profiles), so it's not 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful context by revealing that the tool probes each entity via ai_visibility_check, ranks results, and returns per-entity metrics (score, confidence, signal density), giving agents a clear behavioral model 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 three tight sentences that front-load the main action, then add behavioral detail, a use case, and output format. 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?

With no output schema present, the description compensates by explicitly listing return fields (ranked list with score, confidence, signal density). It also explains the probe-and-rank workflow and the number of entities involved, making the tool's behavior fully understandable for decision-making.

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 minimal parameter-specific meaning beyond the schema, mostly restating the 'your brand + competitors' relationship already explained in the entities parameter description.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It explicitly differentiates from sibling ai_visibility_check by emphasizing multi-entity comparison, ranking, and 'most/least recognized' 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 a concrete use case: 'competitive AI-marketing audits' with an illustrative question. It clearly implies this is for comparing multiple entities rather than a single check, but does not explicitly state when not to use it or name alternatives beyond referencing ai_visibility_check.

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 and idempotent hints, so the description adds substantial behavioral context: it fans out to two services, returns a specific summary block, degrades gracefully on partial failures, and warns about a 5-30s possible delay for bundlephobia's first measurement. 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?

Every sentence earns its place: purpose, usage triggers, return fields, ecosystem scope, and failure behavior are all covered without redundancy. The description is front-loaded with the core use case and keeps the remaining info tightly packed.

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 listing the exact summary block fields, per-advisory detail, links, and alternative versions. It also covers timing, partial failure behavior, and ecosystem scope, making it complete for a complex composite tool.

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

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

Input schema covers both `package` and `version` with descriptions (100% coverage). The description adds no new parameter-level semantics beyond the schema; it only restates npm scope in prose. Per rubric, baseline 3 is appropriate when schema covers fully.

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

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

The description uses a specific verb ('scan') and resource ('npm package'), and explicitly labels itself as a 'Composite check' aggregating deps.dev and bundlephobia. It clearly distinguishes itself from sibling tools by naming its cross-service scope and NPM-only ecosystem.

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

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

Provides explicit usage triggers ('Use whenever an agent asks "is X safe / popular / small"...') and an explicit exclusion for non-NPM ecosystems, directing users to 'deps.dev:version directly'. This covers both when and when-not to use the 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses significant behavioral details: truncation at 200K chars with a flag, the embedding model and windowing strategy, and the return of offsets/scores. This exceeds what annotations provide and fully informs the agent of the tool's limits and output characteristics.

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

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

The description is dense but well-organized: purpose, usage scenario, complementary tool, implementation details, and limits. Every sentence carries useful information with no filler, and it front-loads the core 'semantic search inside a fetched record' concept immediately.

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 compensates by explaining the return format (passages with character offsets and similarity scores), the 200K char cap and truncation flag, and how it fits into a larger workflow. This is complete for a complex search tool.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds practical semantics by explaining what kind of text to pass (e.g., SEC 10-K body, article, long tool result), clarifies the 'query' is natural-language, and describes the result format (top-N passages with offsets/scores). This enhances the schema's basic descriptions without duplicating them.

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: 'Semantic search INSIDE a fetched record.' It clearly differentiates from siblings by emphasizing it operates on already-fetched text and explicitly mentions pairing with ask_pipeworx_grounded, making its unique niche obvious.

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 when the record is too big to cram into the prompt' and 'saves context, returns only the passages that matter.' It also names an alternative/companion tool (ask_pipeworx_grounded) and explains how they combine, giving clear when-to-use and when-not-to-use context.

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

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

The description adds extensive context beyond annotations: auth requirements, inability for anonymous/BYO accounts to persist, phone verification and daily caps, webhook auto-disable after failures, and one-time signing secret. These are valuable behavioral traits not captured by 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 dense but well-structured, starting with purpose, then return value, prerequisites, types, and delivery options. Each sentence contributes useful information, though it reads as a long paragraph that could benefit from formatting.

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

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

Given the tool's complexity and lack of output schema, the description covers the essential return (subscription id), delivery channels, and how to pull from the feed. It also mentions the webhook signing secret once, making it reasonably complete, though it doesn't detail full response structure.

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 goes beyond the schema by explaining the meaning of specific item codes (e.g., items:['5.02'] = officer change) and provides concrete examples for each subscription type, adding semantic 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 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation, and details supported types.

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

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

The description explains when to use the tool (to subscribe to live data events) and includes prerequisites like requiring a Pipeworx OAuth account. It doesn't explicitly name alternatives but implies how it relates to recent_alerts and list_subscriptions via the persistent feed, giving clear context.

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

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

Annotations already declare this as read-only, open-world, and non-destructive. The description adds valuable behavioral context: it returns category-bucketed example questions, includes exact tool + argument shapes, and explains the behavior for no-arguments vs. topic-passing. It also notes that the catalog is live and contains thousands of tools, which is useful without contradicting 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 verbose but information-dense, front-loaded with example user intents. Every sentence contributes purpose, usage guidance, or parameter explanation. It could be tightened slightly, but the length is justified for an onboarding tool.

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

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

Given there is no output schema, the description adequately explains what the tool returns (category-bucketed example questions with exact tool + argument shapes). It covers both invocation modes (no args and with topic) and contextualizes the tool as the first step for a newly connected agent. The complexity is well served by this description.

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 repeats the topic options and adds an example ('e.g. "finance", "pharma", "betting"'), but this is marginal beyond the schema. It does not add syntax or format 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?

The description clearly identifies the tool as the onboarding entry point for discovering what questions to ask Pipeworx. It specifies the verb ('returns category-bucketed example questions'), the resource (the live catalog of tools), and distinguishes it from siblings like discover_tools by focusing on example questions with exact tool + argument shapes.

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

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

The description explicitly states when to use this tool: '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 does not explicitly mention alternatives or exclusions, but the 'FIRST' guidance and onboarding context make the intended usage clear.

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

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

The description adds important behavioral details beyond annotations: ownership enforcement (only your own subscriptions) and the soft-delete semantics (deactivated, not deleted, historical events remain via recent_alerts). 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?

Two sentences, front-loaded with the action. No wasted words; each sentence contributes meaningful 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 simple signature (1 param, no output schema) and rich annotations, the description fully covers the essential context: how to use it, ownership constraints, and the non-destructive nature. It connects to recent_alerts for historical visibility.

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 schema already documents 'id' as a UUID returned by subscribe. The description merely says 'by id' without adding new meaning, so the 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 uses a specific verb ('Cancel') and resource ('subscription') with the method ('by id'). It clearly distinguishes from siblings like subscribe and list_subscriptions, and adds ownership enforcement for precision.

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 intended use is clear: cancel a subscription by id. While it doesn't explicitly name alternatives or exclusions, the ownership constraint and soft-delete behavior provide useful context. It could further mention checking list_subscriptions for valid ids, but this is not a major gap.

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 adds crucial behavioral context: the meaning of 'could_not_verify' (check did not happen, not evidence), the distinction with 'unsupported', the routing to structured vs. grounded pipelines, and the verdict list. This is significant additional transparency 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 dense but well-structured: it opens with trigger examples, states the purpose, outlines the two processing paths, describes output, and highlights important caller caveats. Every sentence adds value, and the front-loading with example phrasings aids quick comprehension.

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

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

With no output schema, the description must explain what the tool returns, which it does thoroughly (verdicts, citations, reasoning, error semantics). It also covers edge cases (could_not_verify vs. unsupported), source flexibility, and performance context (replacing sequential calls). For a complex tool, this 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?

Schema coverage is 100%, so the baseline is 3. The description includes examples of the 'claim' parameter but adds no new semantics for 'tolerance_pct' beyond what the schema already explains (max deviation, defaults, overrides). No extra guidance is provided that isn't already in the schema.

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

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

The description opens with natural-language trigger phrases and states 'natural-language claim verification against authoritative sources,' giving a specific verb and resource. It clearly distinguishes this from siblings by describing the structured SEC EDGAR path for financial claims and the grounded pipeline for everything else, and notes it replaces 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It does not name explicit alternatives or exclusions, but it does describe internal routing (financial vs. other claims), which guides usage.

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