Market Recap

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful context: default model is free, passing _apiKey incurs direct cost to the user, and it explains the return structure. This goes beyond the annotations and clarifies financial implications.

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

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

The description is four sentences, front-loaded with the primary action, and every sentence provides useful information. No fluff or repetition.

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

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

With no output schema, the description compensates by listing the exact return fields ({score, confidence, signals, raw_response} + combined view). It also covers parameter defaults, cost implications, and use cases, making the tool understandable without additional documentation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the specific model name (Llama-3.3-70b) and emphasizes that default is free, which is more specific than the schema's 'workers-ai (free default)'. It reinforces the relationship between _apiKey and anthropic model.

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 ('Probe') and resource ('one or more LLMs'), and clearly states the output (visibility score 0-100 per model). It distinguishes itself from sibling tools by focusing on probing LLM knowledge for any entity, unlike tools like scan_competitor_ai_presence or validate_claim.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic key. However, it does not explicitly contrast with alternative 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?

Annotations already signal readOnly/idempotent/open-world/non-destructive. The description adds useful behavioral detail: it routes to one of 5,718 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs.

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

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

The description is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'), provides memorable examples, and then covers alternatives. Every sentence earns its place with no redundant 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 tool with no output schema, it adequately explains what the agent gets back: a structured answer with stable citation URIs. It also covers when to prefer alternatives. Minor gaps exist around failure behavior, but not enough to make the tool hard to invoke.

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

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

Schema coverage is 100%, so each of the six parameters is already documented as an alias for the question. The description reinforces that free-form natural language is expected, but does not need to add parameter-level details.

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 default for factual/current/historical questions about authoritative data, with specific domains and example queries. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

It gives explicit direction: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and states exactly when to use ask_pipeworx_grounded and deep_research instead. This is unusually actionable routing guidance.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: it is an experimental edge, no candidate is currently active, it currently matches ask_pipeworx exactly, and it does not fall back to anything—it is a full working router. This is transparent and does not contradict the annotations.

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

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

The description is compact and front-loaded with the essential identity ('Beta version of ask_pipeworx') and usage guidance. There is minor redundancy between 'identical universal router' and 'currently matches ask_pipeworx exactly,' but overall every sentence contributes useful context and there is no filler.

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

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

Given no output schema, the description helpfully states that the response shape is identical to ask_pipeworx, and it fully explains the current experimental state, the absence of an active candidate, and the absence of fallback behavior. It is complete enough for an agent to decide when to use it, though it relies on knowing ask_pipeworx's response shape rather than spelling it out.

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 documented as aliases for the single required 'question' parameter. The description adds only that it accepts the same arguments as ask_pipeworx, which is useful but does not provide any additional parameter-level meaning beyond the schema.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router accepting the same arguments and returning the same response shape. It distinguishes the tool's experimental routing intent from the stable sibling, though the primary operation remains general ('ask a question') rather than a more specialized verb.

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 says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. This gives clear context, but it does not explicitly state when NOT to use it, such as preferring the stable ask_pipeworx for production purposes or ask_pipeworx_grounded for grounded answers.

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 behavior well beyond the annotations: it guarantees answers are extracted only from tool results, specifies the success payload with verbatim evidence and confidence, and enumerates explicit refusal reasons. This is valuable because annotations only mark the operation as read-only, open-world, and idempotent; there is no 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?

The description is dense but every sentence carries distinct value: the mode, the routing and extraction mechanism, the return/refusal contract, the high-stakes use cases, and the cost-based comparison with ask_pipeworx. It front-loads the core purpose before diving into response details, and has no filler.

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

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

Even though there is no output schema, the description fully defines both success and refusal response shapes, explains when to use the tool, and names the preferred alternative with rationale. Combined with the annotations and schema, an agent has everything it needs to invoke the tool correctly and interpret its result.

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

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

The input schema already documents the single required 'question' parameter and all aliases with 100% coverage, so the description does not need to repeat parameter details. The description adds useful context about how the question is routed and grounded, but it does not introduce parameter-level semantics 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 states a concrete function: a hallucination-resistant answer mode that extracts answers only from fetched tool results, with explicit success and refusal shapes. It clearly distinguishes itself from ask_pipeworx by emphasizing grounded evidence and refusal behavior, so an agent can tell the tools apart without inspecting schemas.

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

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

It explicitly says when to use it: high-stakes reads where answers will be quoted, cited, or acted on and the agent must not invent facts, citing financial, legal, medical, and public-statement examples. It also names the alternative, ask_pipeworx, and says to prefer that for casual lookups, including the cost tradeoff of one extra LLM call.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavior: resolver confidence contract (low/medium/high/none), blocking statuses (low_confidence_match, market_closed_or_inactive), 24h-move warning, illiquid_wide_spread flag, GDELT 429 fallback mechanics, and cancellation-rule risk. No contradiction with annotations.

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

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

The description is exceptionally long but well-structured with section headers, bolded labels, and dense, relevant details. It is front-loaded with the core purpose and input formats. Some redundancy exists (e.g., closed-market behavior described twice), but each section earns its place for a tool with this complexity.

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

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

Given the lack of an output schema and the tool's complexity, the description is remarkably complete: it details input normalization, classifier list, fan-out examples, response shapes, resolver contract, parent-event extraction, news fallback, safety statuses, and cancellation-rule risk. There is little left for an agent to guess.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by explaining the market parameter's flexible input forms (slug/URL/question text), depth quick vs thorough semantics, and include_raw size implications. The fan-out examples also clarify how parameter values map to different data sources.

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

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

Opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines accepted inputs (slug, URL, question text) and describes the pipeline (resolve, classify, fan out), distinguishing itself from sibling research tools via its unique market-vs-model comparison and 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 cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which is clear contextual guidance. However, it does not name alternative tools or explicitly state when not to use this tool, so it falls short of the highest bar.

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 specific data sources (SEC EDGAR/XBRL, FAERS), metrics (revenue, net income, cash, long-term debt, adverse-event counts), edge-case handling (off-calendar fiscal years), sorting behavior, and return format (paired data + citation URIs). This goes far beyond the annotations' read-only hints.

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, opening with common user phrasings, then stating core function, preference rule, and per-type details. Every sentence provides actionable information without redundancy.

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

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

Given no output schema, the description fully covers return values (paired data + citation URIs), sorting order, entity count limits, and data sources. For a comparison tool with 2 parameters, this is complete and leaves no critical ambiguity.

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

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

Despite full schema coverage, the description adds deep semantic value by explaining what each type ('company' or 'drug') returns, including data metrics and fiscal year handling. This clarifies the enum values beyond the schema, compensating for no output 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 it performs side-by-side comparison of 2–5 companies or drugs in a single call, with specific examples of user intent. It distinguishes this from sequential single-pack lookups by emphasizing 'ALWAYS PREFER', making the tool's 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 provides explicit guidance to prefer this tool over sequential lookups when comparing entities and lists trigger phrases. However, it does not name alternative tools like entity_profile for single-entity lookups, so the exclusions are less explicit than the highest bar.

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 say readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description goes beyond annotations by disclosing account requirements, paid depth tier, latency expectations (15-60s; ~90s for thorough), gap[]/contradictions[] behaviors, hop field, citation_uri fetchability, semantic excerpting rather than head-truncation, and parallel tool routing. This richly discloses behavioral traits beyond what annotations provide.

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

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

The description is long but information-dense; nearly every sentence adds behavioral or routing context. The usage guidance is front-loaded at the top, which is helpful. It is not maximally concise—some parentheticals could be tightened—but it earns most of its length with critical caveats and behavioral 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?

Given this is a complex tool with no output schema, the description compensates fully: it documents return shape (findings packet elements: evidence, confidence, source, fetched_at, citation_uri, hop, gaps[], contradictions[]), latency, auth, alternatives, and depth tiers. An agent has enough to call it correctly and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics: it explains what depth levels actually do (facet counts, hop behavior, contradictions[]), exceeding the schema's enum descriptions. It frames 'question' as naturally broad/multi-part, aligning with the decomposition behavior. Slight gap: no explicit mention that question is the only required param, but the schema already conveys that. Strong added value over 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1496 STRUCTURED data sources... in ONE call'. It clearly distinguishes from open-web search and mentions sibling ask_pipeworx explicitly, so an agent can differentiate. The scope and output type are clearly listed.

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

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

Explicit when-to-use: 'Best for broad/multi-part questions over structured data'. It also gives a when-not-to-use: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead'. It names alternatives and conditions directly. This is exemplary routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral detail beyond the annotations: it explicitly states the return format (top-N tools with names, descriptions, and full schemas) and the 'ready to call directly, no second schema lookup needed' property, giving the agent a clear expectation of what happens.

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 long, front-loaded with the core purpose, followed by a domain list and return behavior. Every sentence serves a purpose; 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?

Despite lacking an output schema, the description fully explains the return value (top-N tools with schemas and examples) and provides strong usage context. It is self-sufficient for an agent to decide when to invoke this tool and what to expect.

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

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

Schema description coverage is 100% with clear descriptions for all parameters including aliases. The description adds domain examples for query formulation but does not elaborate on individual parameter semantics. Baseline 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Find tools by describing the data or task.' It also enumerates concrete data domains (SEC filings, FDA drugs, etc.), which distinguishes it from sibling tools that perform specific research tasks.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies when not to use it (when you already have a specific answer) without needing to name 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 this as a safe, read-only, idempotent operation. The description adds valuable behavioral details beyond annotations: it fans out in parallel, lists specific return fields, and discloses that the USPTO patents source 'sunset May 2025 — soft-fails until reactivated' and that news uses a GDELT→GNews fallback. It doesn't mention rate limits or auth, but the added context is strong.

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 each sentence carries weight. It front-loads with example prompts, then states the core purpose, usage preference, return details, and parameter constraints. It's more verbose than ideal, but justified given the tool's complexity and multiple data sources.

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

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

With no output schema, the description fully compensates by enumerating the return structure: cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, and LEI. It also covers source behaviors (parallel fan-out, fallbacks, soft-fail) and input formatting, making it nearly complete for an agent to use 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?

The input schema already covers 100% of parameters with descriptions for both 'type' and 'value'. The description reinforces with concrete examples ('AAPL', '0000320193') and reiterates the name limitation, but doesn't add significant new meaning beyond what the schema provides. 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 is exceptionally clear: it states the tool produces 'a full cross-source profile of a US public company in ONE parallel call' and provides concrete example queries. It also distinguishes itself from chained single-pack lookups and from sibling tools like resolve_entity, making its purpose unambiguous.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and clearly notes that names are not supported, directing the agent to use resolve_entity first. This provides both when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructive and idempotent behavior, and the description adds context about clearing sensitive data and the tool's role in the memory lifecycle. It doesn't contradict annotations and provides extra behavioral context beyond the safety profile.

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 action, and includes only necessary guidance 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?

For a simple one-parameter destructive tool with annotations covering safety and idempotency, the description provides the necessary usage context and role within the tool family. No output schema is needed, and the description is complete.

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

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

The schema has full coverage for the single 'key' parameter with description 'Memory key to delete,' and the description restates it without adding new details such as format or validation rules. Therefore the description adds no significant value beyond the schema.

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

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

The description clearly states the tool deletes a memory by key, using the specific verb 'Delete' and resource 'memory.' It also differentiates from siblings by referencing the 'remember and recall' trio, making its role as the deletion counterpart explicit.

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 provides usage conditions: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, implying alternatives for storage and retrieval.

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

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

Adds behavioral details beyond annotations by describing the fetch-extract-emit workflow and the output as a single text blob. Annotations already cover readOnly/idempotent/destructive hints, so the description supplements rather than contradicts 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?

Three sentences, front-loaded with purpose, then process, then use cases. Every sentence contributes value with no fluff 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?

Even without an output schema, the description explains the return format ('single text blob'), the standard llms.txt format, and practical use cases. With only 2 simple parameters, the description is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and already describes both parameters with meaning. The description only rephrases 'any URL' and does not add new parameter semantics, 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?

Clearly states it generates a production-ready llms.txt file for any URL, with specific actions (fetches, extracts title/description/key links) and emits standard markdown format. This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

Provides 'Useful for' scenarios (client indexing, drafting for own project, competitor auditing) that frame when to apply the tool. Does not explicitly mention alternatives or when-not-to-use, but the use cases give 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 readOnly and idempotent, but the description adds important context: keyless access (Yahoo Finance), return fields (current price, previous close, change, daily % change), and accepted symbol formats (^, =X). This goes beyond 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 dense but well-structured: it opens with the key usage directive, then details supported symbols and return data, and closes with an alternative tool. Every sentence contributes useful information; 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?

With an output schema present, the description need not detail return values. It fully covers input semantics, symbol formats, and tool placement versus siblings. For a simple one-parameter tool, this is complete and actionable.

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 the single parameter with 100% description coverage, but the description enhances meaning with concrete symbol examples (^GSPC, AAPL, BTC-USD, EURUSD=X) and notes that comma-separated strings are accepted. This adds practical guidance 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 states a specific verb+resource ('get current quotes by symbol') and clearly distinguishes from siblings like web search and market_snapshot. It enumerates asset classes (stocks, indices, crypto, FX, commodities) and provides concrete examples, making the tool's purpose unambiguous.

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

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

Explicitly instructs 'PREFER OVER WEB SEARCH' for current quotes, and names market_snapshot as the alternative for a broader market recap. It also gives example queries and clarifies symbol requirements, leaving no doubt when to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by specifying the exact return fields and clarifying that only active subscriptions are listed by default (with inactive optionally included), which complements 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 two sentences: the first front-loads the action and return fields, the second gives usage context. Every detail earns its place, with no redundant or vague language.

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 list tool with one optional parameter, the description covers the return format explicitly, the default active-only scope, and the intended use cases. Combined with the rich annotations (read-only, idempotent, non-destructive), it is fully self-sufficient for an agent to select and invoke correctly.

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

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

The input schema has 100% coverage for the single parameter include_inactive, with its own description. The tool description's phrase 'active subscriptions' implicitly reinforces the default behavior but does not add meaning beyond what the schema already provides, 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 uses the specific verb 'List' with resource 'subscriptions' and clearly scopes to 'the caller's active subscriptions,' distinguishing it from sibling tools like subscribe and unsubscribe. The return fields are explicitly enumerated, leaving no ambiguity about what the tool does.

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

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

The description gives explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool, though it doesn't explicitly mention alternatives or when-not-to-use, so it stops 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 indicate read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context by stating it is 'Live', returns 'structured numbers', and is 'Keyless (Yahoo Finance)', which discloses the data source and auth requirement. It does not contradict 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 efficiently structured with a front-loaded summary, then defaults, usage, output type, and auth note. Every sentence adds value, and the dense but organized listing of asset classes avoids unnecessary words.

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

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

Given the tool has only one optional parameter with full enum documentation, the description covers the critical context: what the tool returns, the default scope, how to narrow by region, the output format (structured numbers), and the fact that no key is required. No output schema exists, but the narrative description sufficiently explains the return value 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?

Schema coverage is 100% and the region parameter is fully described with an enum. The description goes beyond the schema by detailing the default headline composition (Asia + Europe + US futures + 10Y + DXY + oil + gold + BTC) and framing region as a way to 'drill into one group,' adding practical meaning to the parameter.

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

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

The description clearly states the tool provides a live market snapshot for a recap, listing the exact asset classes covered (major indices, Treasury yields, FX, commodities, crypto) and how data is grouped by region. This distinguishes it from sibling tools like get_quotes or top_movers by focusing on a curated, group-level overview rather than individual quotes or movers.

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

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

The description gives clear context for when this tool is appropriate ('what happened in markets' recap), explains the default headline behavior, and instructs to 'Use region to drill into one group.' It does not explicitly mention when not to use it or suggest alternatives, but the default and region guidance provide solid usage direction.

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

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

Discloses rate limiting (5 per identifier per day), the claim_token return-and-redeem flow, that the team reads digests daily, and that feedback doesn't count against quota. These are material behaviors not captured in the minimal 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 fairly long but information-dense; each sentence adds practical guidance. Minor redundancy (the 'ONLY for tools served by this connection' point is repeated) prevents a 5.

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 nested context and no output schema, the description covers purpose, usage conditions, exclusions, token mechanics, rate limits, and content guidance. It fully compensates for the lack of annotations and output schema.

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

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

Schema descriptions already cover all parameters at 100%. The description adds valuable semantics on claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) with no other arguments') and advises describing issues in terms of Pipeworx tools/packs, which aids correct parameter filling.

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 verb-object statement ('Tell the Pipeworx team something is broken, missing, or needs to exist') and distinguishes this from all sibling research tools by focusing solely on feedback about Pipeworx itself.

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 (bug, feature/data_gap, praise) and when not to (tools from other MCP servers), including a fallback instruction to file with that server instead. This is exemplary when-to-use guidance.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description goes beyond by disclosing that it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on the window. These are meaningful behavioral traits not present in 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 well-structured and efficient. It front-loads the core purpose, then lists return items and use cases in a scannable format. Every sentence provides value, and there is 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 tool with one optional parameter and no output schema, the description is very complete. It explains what the tool returns (top tools, top packs, total call volume, and the aggregation details), gives use cases, and discloses caching and PII behavior. Nothing essential is missing.

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

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

The single parameter 'window' is fully documented in the schema with an enum and a clear description of how short vs. long windows behave. The tool description only echoes the available windows and adds a caching note, which is more about behavior than parameter meaning. With 100% schema coverage, a 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 opens with a specific, action-oriented statement: 'What other AI agents are calling on Pipeworx right now.' It then details exactly what it returns (top tools, top packs, total call volume) and the time windows. This clearly distinguishes it from siblings like discover_tools and market_snapshot.

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 an explicit 'Useful for' list with three concrete use cases (discovering hot data sources, confirming canonical tool choice, checking alignment with agent needs). This gives clear when-to-use guidance, but it does not mention when not to use the tool or alternative tools, so it stops 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?

Beyond the readOnly/openWorld/idempotent annotations, the description reveals rich behavioral detail: the 3pp threshold for signals, placeholder filtering (>20% yields null), Jaccard similarity anchor, and the fill check against live CLOB depth. This gives the agent a strong sense of what happens internally and when not to act.

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

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

The description is long but every sentence earns its place, covering modes, filters, response shape, and trade advisories. It is front-loaded with the core purpose and uses clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to structure complex information without being redundant.

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

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

Given no output schema, the description fully compensates by describing the response structure (opportunities[], partition_check fields). It also explains failure modes like skipped_low_similarity and placeholders_filtered, making the tool's behavior comprehensive 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 schema coverage is 100%, the description significantly enriches parameter meaning: it explains that 'event' accepts slugs or full URLs, defines 'topic' as a seed question, and describes the resulting behavior (monotonicity check, partition check). The no-args mode is also covered, which the schema omits entirely.

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 itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage and explicitly naming the fill-risk tool for custom sizing.

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: no args for trending_scan, 'event' for a specific market, 'topic' for cross-event scanning, and even says 'For custom sizing use polymarket_fill_risk.' It also warns against trading when realizable_edge_pp ≤ 0, which is a clear exclusion condition.

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 is exceptionally transparent, detailing model families, response segments, diagnostics, caching, slippage assumptions, Kelly caps, and a 24h-move warning. It also explains conditions under which opportunities are dropped (placeholder slugs, low liquidity) and why segments might be empty. This goes far beyond the annotations, providing deep behavioral insight.

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, including non-essential details like per-sport alpha values, placeholder slug patterns, and funnel counters. While it uses uppercase labels to organize sections, it is not concise and could overwhelm an agent. A more focused summary would be more effective.

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

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

Given the tool's complexity (9 parameters, multiple model families, no output schema), the description covers all necessary aspects: response top-level structure, field meanings, filter knobs, diagnostics, and limitations. It gives an agent enough context to understand expected outputs and configure the tool appropriately.

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

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

Although schema coverage is 100%, the description adds critical parameter context: it explains why min_kelly doesn't apply to partition arbs, how min_liquidity/max_spread_pp act as tradeable-edge filters, and how slippage_pp affects ranking. This is genuine added meaning that aids correct parameter selection.

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

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

The description opens with a specific, action-oriented statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly identifies the tool's function and differentiates it from siblings like polymarket_arbitrage or polymarket_edge_tracker by emphasizing the Pipeworx data comparison and daily opportunity discovery.

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 phrase 'Built for "what should I bet on today"' gives a clear intended use case, and the note that Fed bets are excluded due to unreliable signals provides a concrete limitation. However, it does not explicitly mention alternative tools for other scenarios, so it stops short of full 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: 60-day snapshot TTL, snapshots only written on cache-miss (explaining data gaps), and that decay numbers are based on daily closes, not intraday. This goes well beyond what annotations provide.

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

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

The description is well-structured with clear sections for purpose, arguments, response, and limitations. It is front-loaded with the core question it answers, and every sentence carries relevant information without redundancy. Despite its length, it earns its size given the tool's complexity.

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

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

There is no output schema, so the description fully explains the return structure: tracked[] with time-series, trend, decay metrics; expired[] with lifespan; and snapshot_dates[]. It also covers limitations like TTL and data gaps. This is complete for a telemetry tool with this level of nuance.

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 both parameters, so the baseline is 3. The description adds minimal extra meaning ('snapshot family' for window) and slightly under-describes days by omitting the clamp minimum of 2 that appears in the schema. It does not meaningfully compensate or add value beyond the schema.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question about edge longevity and decay. It distinguishes itself from the sibling polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides clear context for when to use the tool, emphasizing the difference between a fresh wide edge and a 3-week-old wide edge. However, it does not explicitly mention alternatives or when NOT to use it, so it stops 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?

Even though annotations already declare readOnly/idempotent/non-destructive behavior, the description adds substantial behavioral detail: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and explains that partial basket fills turn an arb into unhedged directional risk. This goes well beyond the annotations and paints a clear picture of what the tool does and its limitations.

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

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

The description is long but dense, and it uses clear SINGLE-MARKET/BASKET sectioning and all-caps reminders for critical information. While every sentence adds value, the length and emphasis patterns make it slightly less scannable than an ideal description; a light reorganization into bullets would improve readability without losing 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 compensates by enumerating the returned fields per mode (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict; theoretical_sum, capture_ratio, profit_usd, thin_legs[], etc.). It also covers the critical edge cases and risk context, making it self-sufficient for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining mode-dependent semantics: market vs event modes, how side and size_usd are interpreted differently in single-market vs basket mode, and the default/clamping behavior. It also clarifies the mutual-exclusivity requirement, which the schema does not enforce.

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

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

The opening sentence 'Realizable-vs-theoretical edge check against live CLOB order-book depth' gives a specific verb and resource, and the tool is clearly distinguished from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk/execution quality. The description also states its exact role in the workflow, removing any ambiguity about 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 explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing concrete triggers. It also explains when not to rely on theoretical edges and why partial basket fills are dangerous, which is strong 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral detail beyond that: whether the delta is a real signal, that 'unknown' legs are never paired, that compatibility_codes can be non-empty even with matched_pairs > 0, and that topic-mode pairings are always unverified. These are exactly the kinds of non-obvious behaviors an agent needs to know. No contradiction with annotations.

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

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

The description is dense but every sentence carries operational value, moving from purpose to modes to response shape to safety cues to a final usage caveat. The most important scoping information is front-loaded, and there is no filler or repetition.

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

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

Since there is no output schema, the description carries full responsibility for explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp with direction, compatibility_codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and dropped-pair counters. It also clarifies ambiguous behavior like codes being non-empty even when matched_pairs > 0. An agent has enough to call and interpret this tool correctly.

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

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

Schema coverage is 100% and each parameter has a description, so the baseline is 3. The tool description adds the mode framework: topic auto-fetches the matching event on each venue, while explicit ticker/slug creates custom pairings. This clarifies how the parameters interact beyond the schema's per-field 'overrides' notes.

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 first sentence names a specific resource and operation: the cross-venue spread between Kalshi and Polymarket for the same resolving question. This clearly distinguishes it from siblings like polymarket_arbitrage by specifying the two venues and the comparison being made. The two modes and safety-field discussion reinforce what the tool is for.

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 lays out two modes—topic shortcuts vs explicit ticker/slug—so an agent knows how to invoke it. It also warns that most pre-mapped topics return compatibility_warning and that pre-mapped ≠ tradeable, giving an important when-not-to-use signal. It does not name alternative sibling tools for exclusion, but the usage context is clear enough.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail: it returns 'each trading day's close WITH the previous close and the computed daily return percent, per symbol' and notes it is 'Keyless (Yahoo Finance).' This goes beyond the annotations, though it stops short of discussing edge cases like holidays or weekends.

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 and front-loaded with the key intent. Every sentence provides essential information—use case, symbol types, return content, and distinction from get_quotes—without 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 compensates by explaining the returned data: 'close WITH the previous close and the computed daily return percent, per symbol.' It also covers the full parameter set, symbol universe, keyless access, and the distinction from current-price tools, making the tool fully understandable.

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

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

Schema coverage is 100%, providing baseline 3, but the description adds value by expanding the symbol semantics: 'same symbol space as get_quotes' and listing categories such as indices, commodities, crypto, and FX. It also reinforces date range behavior with examples, which helps the agent use params correctly.

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's purpose: 'PREFER for HISTORICAL closing prices and daily returns on a specific past date or date range.' It explicitly contrasts with get_quotes and includes concrete examples, making it unmistakable what resource and verb are involved.

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

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

Usage guidance is explicit and actionable: 'Use get_quotes for CURRENT prices; this tool is for any date in the past.' It also states when the tool should be preferred and provides the symbol space context, clearly steering the agent away from inappropriate 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?

Annotations already declare readOnly and idempotent behavior. The description adds valuable context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior of retrieving a single key versus listing all keys. This goes beyond annotation basics, though it could mention error handling for missing keys.

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 tight sentences, front-loaded with the core action. Every phrase earns its place: the retrieve/list distinction, usage guidance, scoping, and sibling references. No fluff 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 tool with a single optional parameter, no output schema, and clear annotations, this description is remarkably complete. It covers purpose, modes of operation, scoping, and how it relates to remember and forget. Nothing essential is missing for an agent to invoke it correctly.

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

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

The schema already documents the 'key' parameter well (100% coverage). The description adds real meaning by giving concrete examples of key values (target ticker, address, prior research notes) and reinforcing the conceptual meaning of omitting the key. This enriches the schema's formal definition.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. It uses specific verbs and resources, and explicitly contrasts with sibling tools 'remember' and 'forget', making its purpose unmistakable.

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

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

It says 'Use to look up context the agent stored earlier — without re-deriving it from scratch', establishing when to use recall. It also explicitly guides pairing: 'Pair with remember to save, forget to delete', clarifying alternatives and exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description goes beyond by disclosing the mark_read side effect (flagging events read), the data fields returned, and the persisted feed location. It also clarifies the polling-friendly nature, adding valuable context not present in annotations.

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

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

The description is a single well-structured paragraph with the main action front-loaded. Every sentence provides useful information, from return payload to filtering, mark_read behavior, and the external endpoint. It is not overly long for a tool with five parameters, though the external URL could be considered extra.

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 appropriately explains the returned fields (source, citation_uri, raw payload). It covers filtering, mark_read semantics, and even provides an alternative access method. It does not mention unread_only in text, but the schema covers it, so the description is complete enough for this simple read tool.

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

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

The input schema covers 100% of parameters, giving a baseline of 3. The description adds value by giving an example for type ("sec_8k"), specifying 'ISO timestamp' for since, and explaining the consequence of mark_read (next call shows only newer events). This elevates it above baseline.

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

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

The description opens with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly states what is returned (most recent alerts with source, citation_uri, raw payload) and distinguishes itself from siblings like list_subscriptions by focusing on fired alerts rather than subscription management.

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: it is suitable for polling ('Polls work fine') and mentions an alternative REST endpoint for scripts/dashboards. However, it does not explicitly state when to prefer this over sibling tools like list_subscriptions or recent_changes, so it falls just 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 indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds value by detailing the parallel fan-out to SEC EDGAR, GDELT/GNews fallback logic, USPTO soft-fail due to API sunset, and the exact return structure (changes[], total_changes, citation URIs). This goes well beyond the annotations.

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

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

The description is dense but well-structured, starting with user-intent examples, then the core definition, fan-out details, and return format. While slightly long, every sentence contributes meaningful information. The structure aids comprehension 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?

The tool is complex with multiple sources, date handling, and fallback logic. The description covers all key aspects: sources, fallback behavior, date formats, return shape, and the alternative tool. Since there is no output schema, explaining the return structure is essential and is done clearly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical guidance for the `since` parameter (ISO date vs relative shorthand, recommended '30d'/'1m') and provides examples for `value` (ticker or CIK). This exceeds schema descriptions, though not exhaustively for all edge cases.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with specific verbs like 'fans out' and 'returns'. It distinguishes from the sibling entity_profile by targeting dynamic changes rather than a static profile. Example queries make the purpose immediately recognizable.

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 ('change feed for a company in the last N days/weeks/months') and when to use an alternative ('Use entity_profile instead when you want the static profile'). Also describes fallback behavior (GDELT→GNews) and soft-fail conditions, giving clear context for when results may be incomplete.

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 substantial behavioral context beyond the annotations: persistence across sessions, scoping by identifier, and the difference between authenticated (persistent) and anonymous (24-hour retention) sessions. These details are not present in the annotations, making the description highly transparent.

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 sized and front-loaded, starting with the core purpose and then expanding into usage and technical details. Every sentence adds value—examples, scoping, retention policy, and sibling references—without redundancy or 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?

For a simple two-parameter tool with no output schema, the description is complete: it covers purpose, usage context, persistence behavior, authentication differences, and relationships with sibling tools. There are 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?

The input schema provides 100% coverage with descriptive examples for both parameters (key and value). The description adds no extra parameter-level details, but the schema already handles semantics adequately, so the baseline score of 3 applies.

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

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

The description clearly states the tool saves data for later reuse, with a specific verb and resource ('Save data'). It provides concrete examples of what to store (e.g., resolved ticker, user preference) and distinguishes it from siblings by describing the key-value pair storage and pairing with recall/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 defines when to use the tool ('Use when you discover something worth carrying forward') and mentions the benefit ('so you don't have to look it up again'). It also names sibling tools for related operations ('Pair with recall to retrieve later, forget to delete'), providing clear 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 and idempotent behavior, and the description adds substantial non-obvious context: the call cascades through several lookup endpoints, LEI/FIGI enrichment degrades gracefully, ambiguous matches assert nothing and return figi_candidates, and unresolved identifiers are explicitly listed rather than omitted. No contradiction with annotations.

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

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

The description is long and dense, but most of the length is earned by non-obvious lookup semantics, examples, and caveats. It is front-loaded with purpose and trigger phrases; minor redundancy and sprawling parentheticals keep it from a perfect structure score.

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

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

Even without an output schema, the description covers resolution outcomes, ambiguity handling, source labeling, unresolved fields, degradation behavior, and supported types. An agent has what it needs to invoke the tool correctly and interpret key result states.

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 meaning far beyond the schema: it explains the 'pass the entity name only' rule with a counterexample, enumerates accepted company inputs (ticker, CIK, ISIN, name), and clarifies ISIN-to-LEI behavior for non-US issuers. This materially helps an agent format parameters correctly.

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

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

The description opens with concrete trigger phrases and a precise verb-resource pair: resolving user-spoken names to canonical identifiers. It enumerates supported types (company/drug), states what each returns, and clearly separates itself from sibling lookup/profile tools by framing itself as the identity-resolution entry point ('Use FIRST whenever you have a name but need an ID').

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

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

The description gives explicit trigger examples and a strong 'Use FIRST whenever you have a name but need an ID' directive, plus input-format guidance. It does not explicitly name or contrast specific sibling alternatives, but the usage context and priority are clear enough for an agent to route correctly.

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 readOnly, openWorld, idempotent, and non-destructive, lowering the bar for description transparency. The description adds valuable behavior beyond that: it says the tool 'Probes each entity ... with ai_visibility_check, ranks by score', and discloses the output fields ('ranked list with score, confidence, signal density per entity'). This is meaningful context that annotations alone don't 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 extremely concise: two sentences (plus a quoted example) accomplish everything. The action is front-loaded, and each sentence adds critical information—the probe method, ranking behavior, return format, and a concrete use case—without any fluff or repetition of schema details.

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

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

With no output schema, the description compensates by clearly stating the return format ('ranked list with score, confidence, signal density per entity'). It also explains the process (probes each entity with ai_visibility_check, ranks by score) and gives a realistic scenario. Minor gaps remain, such as how results are aggregated when multiple models are specified, but for a comparison tool of this complexity the description is sufficiently complete.

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

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

Schema description coverage is 100%—every parameter (entities, models, _apiKey, context) has a thorough description, including the nuance that the first entity is treated as the subject. The tool description adds no additional parameter semantics beyond what the schema already covers; it merely mentions 'your brand + N competitors', which is already implicit in the entities parameter description. Thus the baseline of 3 applies.

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

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

The description opens with the specific action 'Compare AI visibility across multiple entities side-by-side', immediately distinguishing this from single-entity tools like ai_visibility_check. It further clarifies the scope by mentioning 'your brand + N competitors' and naming the exact probing mechanism (ai_visibility_check), making the tool's role completely 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?

Explicitly frames the tool for 'competitive AI-marketing audits' with a concrete example question ('does Claude know about us as well as our competitors?'), giving clear guidance on when to use it. It implies that for a single entity one would use ai_visibility_check instead, but it doesn't explicitly state this exclusion or name other alternative tools, so it falls short of a full when-not-to-use specification.

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 substantial behavioral context beyond the annotations: it describes the fan-out to multiple sources, graceful degradation on partial failures, a potential 5-30s latency for bundlephobia's first measurement, and the sources_failed field. This is valuable information not present in the readOnly/hint 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 and front-loaded with the core purpose, followed by usage triggers, return details, scope, and failure behavior. Every sentence provides value, though the single long paragraph could be slightly more scannable with bullet points. 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?

With no output schema, the description thoroughly enumerates the return contents (summary block fields, per-advisory details, links, alternative versions). It also covers ecosystem scope, timing, and failure degradation, making it complete for an agent to invoke and interpret results.

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

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

The input schema already provides comprehensive descriptions for both parameters (package and version), covering scoped packages and default behavior. The description does not add extra parameter-level semantics beyond what the schema states, so the baseline score of 3 for high schema coverage 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 purpose: a composite check to evaluate whether to add an npm package, aggregating data from deps.dev and bundlephobia. It lists the specific data points (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support) and differentiates from direct deps.dev usage by scoping to NPM ecosystem in v1.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states when NOT to use it: for non-NPM ecosystems, directing to deps.dev:version directly. This clearly distinguishes the tool's appropriate 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?

Goes beyond annotations by disclosing the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, return contents (passages with offsets and scores), and the 200K char cap with truncation flag. No contradiction with readOnlyHint.

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 with clear front-loading of purpose. Each sentence earns its place, covering purpose, use case, sibling relation, and technical details 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?

For a read-only semantic search tool, the description fully covers what it does, when to use it, how it works, and key constraints. Annotations cover safety, so no gaps remain.

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

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

Schema already describes all parameters, but the description adds extra context: real-world examples for text (SEC 10-K, article), query examples, and 'top-N' framing for limit. This enhances understanding 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?

First sentence states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by emphasizing searching within already-fetched text and explicitly pairs with ask_pipeworx_grounded.

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: 'Use when the record is too big to cram into the prompt.' It also names an alternative approach (ask_pipeworx_grounded) and explains how they complement each other.

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, the description discloses auth requirements, delivery channel behavior (feed always on, email/SMS optional, SMS verification and 10/day cap), and webhook security details (HMAC-signed requests, secret returned once, auto-disable after 10 failures). This is extensive behavioral context that significantly aids an agent.

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

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

Though long, the description is well-structured: purpose first, then requirements, supported types, and delivery channels. Every sentence adds substantive detail, with no filler or redundancy, earning its length for a tool with this 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?

The description covers return value, auth, all main types with examples, delivery options with constraints, and webhook security. The two types not detailed in the description (patent_grant, clinical_trial) are described in the input schema, so the description is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, and the description enriches this with concrete examples (e.g., 'items:["5.02"] = officer change' for sec_8k) and clarifies nested params and delivery semantics. It explains the meaning of enum values and gives practical usage patterns, making parameter selection intuitive.

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' and notes it returns the new subscription id, identifying the exact action and resource. This unambiguously distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

Provides concrete usage context: lists supported subscription types with examples, explains prerequisites (OAuth account required, anonymous/BYO cannot persist), and mentions how to retrieve alerts via recent_alerts. However, it does not explicitly name alternatives when not to use this tool, so it lacks explicit exclusions.

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

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

The description discloses behavioral traits beyond the read-only annotations: it returns category-bucketed example questions drawn from the live catalog, with each including exact tool and argument shape. It explains the no-argument vs. topic-focused behavior. Annotations already cover safety (readOnly, idempotent), so the description adds valuable context about output nature and scope.

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 front-loaded with natural language user queries that help with intent matching. Each section earns its place: examples, return value, parameter guidance, and usage instruction. It could be slightly tightened, but the structure is logical and readable.

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 only 1 optional parameter and no output schema, the description fully compensates: it explains what the response contains (category-bucketed example questions with tool+argument shapes), when to use the tool, and how to focus via topic. The description is complete enough for an agent to select and invoke this tool correctly.

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

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

Schema covers the parameter 100%, but the description adds practical semantics: 'Call with no arguments for the full spread, or pass `topic` ... to focus' and provides example values. This goes beyond the schema description by explaining the behavioral effect of omitting vs. providing the parameter.

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 this as the onboarding entry point, with a specific verb ('returns category-bucketed example questions') and resource ('the live catalog of thousands of tools'). It explicitly differentiates from siblings by focusing on generating example questions with exact tool+argument shapes, making it distinct from discover_tools or ask_pipeworx.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also clarifies how to use the optional topic parameter and mentions that it teaches how to call meta-tools. However, it does not explicitly state when not to use it or name alternatives (like discover_tools), but the context is strong.

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, idempotent, non-destructive), the description discloses that it uses live US market data, is keyless (no authentication needed), and details the exact return fields and ranking behavior. This enriches the agent's understanding of what to expect 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 information-dense but every sentence earns its place. It front-loads the core purpose, then usage guidance, parameter details, return data, and a distinguishing note—all without repetition or 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?

For a simple tool with two optional parameters and no output schema, this description is complete. It covers what the tool does, when to use it, what parameters mean, what data is returned, and the data source/authentication requirements.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds value by clarifying category semantics ('gainers (default, biggest % up), losers (biggest % down), actives (highest volume)') and confirming the count default, giving a slight boost to 4.

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

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

The description clearly identifies the tool as returning 'the day's top-moving US stocks by percent change,' with explicit category definitions and return fields. It also distinguishes itself from trending/discussed stocks, which differentiates it from sibling tools like pipeworx_trending.

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

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

The description explicitly instructs to 'PREFER OVER WEB SEARCH' for specific query phrasings, and explains when each category (gainers/losers/actives) should be used. It also excludes trending topics, giving clear when-not 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 goes beyond the annotations by disclosing ownership enforcement and the deactivation behavior (row is deactivated, not deleted), which aligns with destructiveHint=false and idempotentHint=true. It also explains the side effect on historical events, providing valuable behavioral context not present in 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, each providing distinct information: the action, ownership restriction, and deactivation consequence. It is front-loaded with the primary purpose and contains no filler, making it highly concise and well-structured.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential aspects: what it does, constraints, and side effects. It even references the related tool recent_alerts for historical events, making it complete within its 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?

Schema coverage is 100% for the 'id' parameter, so the description adds limited additional meaning. However, it does specify that ownership is enforced, which adds semantic nuance about the required subscription ID (must be your own), enriching the parameter's meaning beyond the schema description.

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

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

The description clearly states the tool cancels a subscription by ID, using the specific verb 'Cancel' with a resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on the cancellation action and ownership enforcement, making the purpose unambiguous.

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

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

The description provides clear context: it is used to cancel subscriptions, with ownership enforced. It does not explicitly state when to avoid using it or name alternatives, but the context is sufficient for an agent to select it over subscribe/list_subscriptions. The note about historical events via recent_alerts adds context on consequences.

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; description adds crucial behavior: 'could_not_verify means the check did not happen ... carries verification_error ... must not be shown as one' and distinguishes unsupported as 'we looked and cover no source'. This goes beyond annotations and prevents misinterpretation.

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

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

Long but dense and front-loaded with query examples; each section (paths, outputs, caveats, replacement benefit) earns its place. No 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?

No output schema, so description compensates by enumerating verdict values, actual value with citation, reasoning, and error semantics. It covers both routing branches and clarifies unsupported vs could_not_verify fully.

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

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

Schema covers both params 100%, but description adds usage nuance: tolerance_pct 'set 1–2 for hallucination detection where any material error must be refuted' and 'Default: implied by wording, capped at 5', plus the exact percent-delta math context for claim. This exceeds schema-only meaning.

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

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

Description opens with natural-language examples and states 'natural-language claim verification against authoritative sources.' It distinguishes the tool from siblings by naming the structured SEC EDGAR/XBRL fast path and grounded fallback, and says it replaces 4–6 sequential calls, making its scope 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 'Use whenever the agent needs to check whether something a user said is factually correct' clearly defines when to call. It describes routing for company-financial vs any other claim, but doesn't name a sibling alternative to prefer or explicitly 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.