Crypto Feeds

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: the free default model, the requirement to pass a BYO Anthropic key, and the direct billing implication. It doesn't cover rate limits or errors, but that's beyond the core safety already expressed.

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 tightly packed sentences: main action, model/cost configuration, and return shape plus use cases. No redundant words or restating of the name. Every sentence earns its place.

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

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

For a tool with no output schema, the description adequately explains both input (entity, models, key, context) and output structure (per-model score/confidence/signals/raw_response + combined view). It omits definitions of 'signals' or 'confidence' and doesn't distinguish itself from similar siblings like scan_competitor_ai_presence, but overall the agent has enough to decide and invoke.

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

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

All parameters are fully documented in the schema (100% coverage), so the baseline is 3. The description adds real semantics: it clarifies the default model for `models`, that `_apiKey` is only needed for Anthropic, and that using Anthropic means paying directly. This goes beyond the schema's property descriptions.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs') and states a precise output: a 0-100 visibility score per model. It clearly differentiates this from sibling tools by focusing on LLM knowledge and model-level scoring, not just generic entity lookup or comparison.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs optional Anthropic model behavior. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide when to use it.

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

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

Annotations already cover safety (readOnly, openWorld, idempotent, non-destructive), and the description adds valuable behavioral context: it routes to one of 5,706 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and is described as a single fast call. It does not detail failure modes or latency, but it goes 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 longer than typical, but every section earns its place: the preference warning, coverage list, trigger examples, default recommendation, and escalation paths are all decision-relevant. It is front-loaded with the most important directive.

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 states the return format (structured answer with stable citation URIs), scope, and alternatives. It gives enough context for an agent to invoke the tool correctly across a wide range of factual questions.

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

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

Schema coverage is 100% and the schema already documents the `question` parameter plus aliases. The description reinforces natural-language usage with examples but does not need to add parameter-level semantics.

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

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

The description states a clear verb-resource pair ('routes the question... returns the structured answer') and specifies the exact domain coverage (SEC, FDA, FRED, etc.). It differentiates itself from ask_pipeworx_grounded and deep_research, so an agent can distinguish it from siblings.

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

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

It includes an explicit 'PREFER OVER WEB SEARCH' directive, trigger phrases, examples, and a 'START HERE' default suggestion. It also names the step-up alternatives and the conditions that select them (hallucination-resistance vs. broad multi-part questions).

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 (read-only, idempotent, non-destructive), the description discloses that candidate routing improvements are enabled live whenever under test, and that no candidate is active right now, so current behavior matches ask_pipeworx exactly. This adds significant contextual behavior about dynamic routing and comparison against the stable router. The description aligns with annotations and provides valuable extra 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 four sentences and information-dense, with the beta identification front-loaded. Every clause adds value, including the specific tool count, retirement date, and comparison mechanism. It is slightly verbose but still well-structured and earns its length.

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

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

Given the complexity of a router with 5,706 tools, the description is quite complete: it covers current state, usage, and how results are evaluated. The lack of an output schema is mitigated by referencing ask_pipeworx's 'same response shape,' though an agent unfamiliar with ask_pipeworx could still be under-informed about the exact return format. Overall, the essential context is present.

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

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

The schema has 100% coverage with clear descriptions for all six parameters, including aliases. The description adds no parameter-specific semantics beyond stating 'same arguments' as ask_pipeworx, so it does not exceed the schema baseline. A score of 3 is appropriate since the schema already fully documents every 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 is a beta version of ask_pipeworx and describes it as a universal router with the same 5,706 tools, arguments, and response shape. This specific verb+resource construction distinguishes it from siblings by naming ask_pipeworx and the experimental difference. The purpose is unambiguous and differentiated.

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 to use it exactly like ask_pipeworx when you want the newest routing, which is a clear usage condition. It also indicates the experimental nature by mentioning results are compared against the stable router, and that no candidate is currently active. However, it does not explicitly say when not to use it, though 'experimental edge' implies a stability trade-off.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds behavioral depth: it explains the extraction-only-from-result guarantee, the explicit refusal structure with refusal_reason values, and the evidence/confidence/fetched_at fields. It even warns about the extra LLM cost. No contradiction with annotations.

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

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

The description is longer than average but every sentence carries information: purpose, routing, extraction mechanism, return shape, refusal reasons, use-case triggers, and cost comparison. It is front-loaded with the most critical differentiator (hallucination-resistant). Slightly dense but not 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 the moderate complexity (single required parameter but nuanced behavior), the description fully specifies the return contract, refusal handling, and usage constraints. There is no output schema, but the description compensates by enumerating return fields and refusal reasons. An agent has everything needed to decide and call 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 provides descriptions for all six parameters, which are aliases for the single question field. The description adds no new semantics beyond confirming the question is natural language, which is already in the schema. With 100% coverage, the baseline of 3 is appropriate.

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

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

The description states a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads' and clearly differentiates from siblings by referencing 'Same routing as ask_pipeworx' and describing the extraction difference. It names the resource and the behavior, so an agent can distinguish it from ask_pipeworx and ask_pipeworx_beta.

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

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

The description gives explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on' with examples of high-stakes contexts, and when-not-to-use: 'prefer ask_pipeworx for casual lookups'. It also notes the cost trade-off ('Costs one extra LLM call'), providing a concrete decision rule.

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 safety, but the description greatly extends behavioral transparency with concrete edge cases: low-confidence short-circuit (status:"low_confidence_match"), closed/inactive market handling (status:"market_closed_or_inactive"), wide-spread market flag (tradeability:"illiquid_wide_spread"), and resolution-rule risk parsing (cancellation_rule with "refund_50_50" etc.). This clearly goes 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 long but well-structured with clear labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loads the primary purpose. While some sections are verbose, they are information-dense and relevant to correct usage; the structured layout aids scanning.

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

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

Given that there is no output schema, the description must compensate by explaining return shapes and edge cases. It does so thoroughly: result.market fields, result.analysis, result.evidence, resolver contract (market_match_confidence), parent_event extractor, news fallback indicators, blocking states, and cancellation-rule risk. This is a complete description for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context (e.g., examples of input formats for the market parameter and depth default values), but most parameter details (depth enum, include_raw behavior) are already fully documented in the input schema. No major gap or extra semantic value above schema.

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

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

The description opens with a specific verb+resource+method: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like validate_claim or deep_research by focusing on market-specific data synthesis and includes concrete input formats (slug/URL/question text).

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

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

Explicit use cases are given: '"should I bet on X", "what does the data say about Y", or "is there edge in Z"' plus classifier and fan-out examples. While it doesn't name alternative tools for exclusions, the context is clear enough for an agent to decide when to call 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?

Discloses multiple behavioral traits beyond annotations: data pulled from SEC EDGAR/XBRL and FAERS, correct handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This adds substantial operational context without contradicting the readOnly/idempotent 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 each sentence carries weight, covering triggers, data sources, fiscal year details, sorting, and output. It is well-front-loaded with common query phrases, though slightly long for a single paragraph.

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

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

Despite no output schema, the description already specifies return format (paired data + citation URIs), data sources, sorting behavior, and scalability benefit. An agent has all necessary information 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?

The schema already covers both parameters with 100% coverage, but the description enriches semantics by explaining what data each type pulls, providing concrete examples, and noting that results are sorted by the primary metric. This goes beyond mere syntax into practical usage.

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

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

The description clearly identifies the tool as a side-by-side comparison of 2–5 companies or drugs, with concrete trigger phrases and data sources. It distinguishes itself from single-entity lookups and sibling tools like entity_profile by emphasizing parallel comparison.

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 to 'ALWAYS PREFER over sequential single-pack lookups' and provides a rich set of trigger examples. Type-specific guidance for company vs. drug makes the appropriate use case unmistakable.

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 rich annotations (readOnly/openWorld/idempotent/non-destructive), the description adds substantial behavior beyond them: never invents answers (explicit gaps[]), returns contradictions[], expectations on latency (15-60s, thorough ~90s), semantic excerpting of large records instead of head-truncation, and the citation_uri guarantee (present only when resources/read can serve it). No contradiction with annotations — readOnlyHint is consistent with a research tool, and openWorldHint is consistent with fetching live multi-source data.

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 well-structured: the gating condition (account/billing) is front-loaded, followed by scope, mechanics, return format, and routing rules. Nearly every sentence earns its place for a tool of this complexity. Slight deduction for redundancy — the depth-tier behavior ('standard re-angles unanswered gaps; thorough chases leads') largely repeats the depth parameter's schema description, and the NOT-open-web point is made twice.

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

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

There is no output schema, so the description carries the full burden of explaining return values — and it delivers: findings packet with verbatim evidence + confidence + source + fetched_at + pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers latency, failure mode (empty gaps for non-catalog topics), and fallback routing. For a tool of this complexity, everything an agent needs to call and interpret it is present.

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

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

Schema coverage is 100% (both question and depth are documented), so the baseline is 3. The description adds genuine value beyond the schema: the billing constraint that depth:'thorough' requires a paid plan, which is critical operational knowledge for parameter selection. It also reinforces that multi-part questions are acceptable, though this already appears in the schema's question description, so the net added value is moderate.

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

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

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1493 STRUCTURED data sources... in ONE call.' It distinguishes itself from open-web search, names its internal mechanics (facets routed in parallel to 5,706 tools), and explicitly names the sibling it is not ('For a single lookup use ask_pipeworx... this is NOT open-web search'). An agent can tell this apart from all 30+ siblings without opening the schema.

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?

Gives explicit when/when-not routing: best for broad/multi-part questions over structured data with concrete examples, and explicitly defers to ask_pipeworx for single lookups and for breaking/news/colloquial topics, including the reason (deep_research returns mostly empty gaps[] for non-catalog topics). Also adds a pre-condition ('If you are not signed in, use ask_pipeworx instead'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: returns top-N relevant tools with full schemas and curated examples, ready to call directly without a second lookup. This complements the annotations without contradiction.

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

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

The description is moderately long but information-dense, with a clear front-loaded purpose and examples of use cases. The domain list adds length but provides concrete examples of what to search for, so every sentence earns its place.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Combined with simple parameters and complete annotations, this is fully sufficient.

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

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

Schema description coverage is 100% (all parameters including aliases and limit are documented). The description mentions 'describing the data or task' and 'top-N,' which map to query and limit, but adds no significant detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task' with a specific verb and resource, and distinguishes itself from sibling tools by positioning as the discovery/meta tool. It lists many domains to search, making the scope concrete.

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 provides 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.' It also implies the alternative of calling a specific tool directly via 'not just one answer.'

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

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

Despite annotations already marking the tool as read-only, idempotent, and non-destructive, the description adds valuable behavioral context: it fans out across multiple data sources, returns specific field names, includes fallback mechanisms (GDELT→GNews), and discloses that the USPTO PatentsView API sunset soft-fails. This goes well beyond what annotations convey.

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

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

The description is a single dense paragraph but front-loaded with example queries and a key usage directive ('ALWAYS PREFER'). While longer than the two-sentence ideal, every sentence packs critical information about sources, outputs, and limitations—no filler. Structure is logical with clear sections for returns and input constraints.

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 carries the burden of explaining return values, enumerating all returned data (cik, recent_filings with pipeworx URIs, fundamentals, patents, news, LEI) and limitations (max 5 filings, patents soft-fail, ticker/CIK only). It accounts for the tool's cross-source complexity and provides enough contextual detail for an agent to use it effectively without further lookups.

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

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

Schema already covers both parameters 100% with descriptions, giving a baseline of 3. The description adds extra semantic value by providing concrete examples ('AAPL', '0000320193'), reinforcing the names-not-supported constraint, and explicitly instructing to use resolve_entity when a name is supplied. This enriches parameter meaning beyond the schema.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call', listing concrete inputs and outputs. It distinguishes itself from siblings like compare_entities and resolve_entity by focusing on single-entity holistic profiles and explicitly says to prefer it over chaining single-pack lookups.

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

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

Provides explicit when-to-use guidance with example phrases ('Tell me about X', 'research Acme', 'brief me on Tesla') and states when not to use it ('names not supported — use resolve_entity first'). It also gives exclusions (only US public companies, only ticker/CIK) and alternatives, making usage boundaries crystal clear.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds valuable context: 'CF-robust: fetches directly and falls back to a proxy if the source blocks the gateway.' This explains network behavior and resilience, which annotations do not cover.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence earns its place: the first defines the function, the second provides usage guidance and a behavioral feature. 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?

Despite lacking an output schema, the description sufficiently covers the tool's behavior: what it does (fetch and normalize), its input scope (any feed by URL), its resilience (proxy fallback), and its positioning relative to curated sources. For a read-only fetch tool, this is complete.

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

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

Schema coverage is 100%, so all parameters are already described. The description adds no additional parameter-level meaning beyond the schema; it mainly reinforces the 'url' scope with 'any RSS / Atom / RDF feed,' which is already implied by the schema's example.

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

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

The description clearly states a specific verb and resource: 'Fetch and normalize any RSS / Atom / RDF feed by URL.' It distinguishes itself from sibling tools like read_feed and list_feeds by emphasizing arbitrary URL fetching and normalization, plus the CF-robust fallback behavior.

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 'Use list_feeds first for curated sources,' providing a clear alternative and when to use it. This gives the agent actionable guidance on tool selection.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower. The description adds context that memory was 'saved earlier' and frames deletion as clearing sensitive data, which enriches the safety profile without contradicting annotations.

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

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

Three purposeful sentences: function, when-to-use, and related tools. No redundant words, and the most important information is front-loaded. Ideal conciseness.

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 single-parameter tool with good annotations, the description covers purpose, usage context, and related tools. It doesn't explain behavior for missing keys, but idempotentHint mitigates that gap. Slight room for more edge-case detail, but otherwise complete.

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

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

Schema coverage is 100% with a clear description for the key parameter ('Memory key to delete'). The description's 'by key' adds no new semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly states what the tool does and distinguishes it from siblings like remember (store) and recall (retrieve).

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

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

Explicit usage conditions are provided: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools ('Pair with remember and recall'), giving direct alternative 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals the underlying behavior: fetching the page, extracting title/description/key links, and emitting standard llms.txt format. It also clarifies the output is a single ready-to-drop text blob, adding valuable context 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 three sentences, front-loaded with the main purpose, then the mechanism, then use cases. Every sentence adds value and there is no redundant or promotional 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?

Despite lacking an output schema, the description explicitly states the result is a single text blob in standard llms.txt format, compensating for the missing return-value specification. It also covers typical use cases and the operational process, making the tool fully contextual for a simple two-parameter 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 provides 100% coverage for both parameters (url and max_links), including descriptions and defaults. The description adds no additional parameter-level detail, so it appropriately relies on the schema's baseline coverage.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, and elaborates on the process (fetches, extracts, emits). It distinguishes itself from related AI-crawler siblings by focusing specifically on producing the llms.txt artifact.

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 (client indexing, drafting for own project, auditing competitor visibility) that signal when to invoke the tool. It does not name alternative tools or state exclusions, but the context is clear enough for an agent to make a selection.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds that feeds are 'curated' and mentions filtering options, both of which set expectations about scope. It does not detail pagination or response format, but for a list tool this is adequate.

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

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

Two sentences, front-loaded with the main action, then filters, then a pointer to read_feed. No wasted words.

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

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

For a simple list tool with two optional params and no output schema, the description covers what it returns, filtering, and next steps. It is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100% with both query and category already described. The description repeats similar filter semantics without adding new value, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('curated crypto feeds'), and enumerates the returned fields (id, title, category, source). It clearly distinguishes from siblings by noting 'Pass an id to read_feed'.

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

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

It explicitly states optional filtering by category or keyword, and directs the agent to read_feed for reading a specific feed, providing an immediate alternative. This gives clear context on when to use this tool versus siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: it returns only active subscriptions by default, scopes to the caller, and lists the exact fields returned. 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?

Two sentences, front-loaded with the core action and resource. The first sentence states purpose and return fields; the second gives usage guidance. No wasted words or redundant repetition.

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

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

Given the low complexity (one optional parameter, no output schema), the description fully covers what the agent needs: scope, return fields, and when to use it. It even compensates for the lack of an output schema by listing the return fields explicitly.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, and the schema description is clear. The description doesn't explicitly discuss the parameter but implicitly references active vs. inactive subscriptions, which is consistent. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb ('List') and identifies the resource as 'the caller's active subscriptions.' It clearly distinguishes this from siblings like subscribe and unsubscribe, and it enumerates the returned fields, 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?

It explicitly states when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implies alternatives (subscribe/unsubscribe) for other actions.

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 (which only set hints to false), the description discloses rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the mechanism for anonymous filing ('Filing without an account returns a `claim_token`'), and the follow-up pattern to check resolution. It also states the team reads digests daily and that feedback affects roadmap, giving the agent a clear picture of side effects and response latency.

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

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

The description is front-loaded with a one-sentence purpose and then flows through conditions, exclusions, usage patterns, and behaviors. It is dense but every sentence adds distinct information (scope, framing, anonymous token, rate limit, cost). No redundant filler; the length is justified by the amount of operational guidance.

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

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

For a feedback tool with four parameters and no formal output schema, the description covers the full lifecycle: when to file, what to include, what to exclude, how to follow up via claim_token, rate limits, and team responsiveness. It integrates with the schema's parameter descriptions and requires no additional context to invoke correctly. It also differentiates from sibling tools by boundary conditions.

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

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

Although the input schema already provides full descriptions for all four parameters (100% coverage), the description adds operational nuance: it clarifies how `claim_token` is obtained and used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs the agent to describe issues in terms of Pipeworx tools/packs, which informs how to fill `message` and `context`. This goes beyond the schema by explaining the expected workflow and framing.

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

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

The description opens with a specific verb and resource ('Tell the Pipeworx team something is broken, missing, or needs to exist'), immediately distinguishing it from sibling tools like ask_pipeworx, discover_tools, and subscription managers. It clearly conveys that this is the feedback channel for the Pipeworx connection, not a general inquiry or data retrieval tool.

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

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

Explicitly enumerates when to use it ('when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well') and when not to ('ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead'). It also provides framing guidance about describing issues in terms of Pipeworx tools/packs rather than pasting end-user prompts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond this: it reveals the data source ('derived from CF analytics-engine'), confirms no PII ('no PII, just (pack, tool, count)'), and explains caching behavior ('Cached 5min-1h depending on window'). This gives the agent a strong sense of what to expect.

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

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

The description is a single, well-structured paragraph that front-loads the core function, then uses a numbered 'Useful for' list and a final sentence on data provenance/caching. Every sentence contributes meaningful information, with no filler or redundancy. It is concise yet information-dense.

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

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

Despite having no output schema, the description tells the agent exactly what to expect: top tools, top packs, total call volume, and the (pack, tool, count) format. It also covers caching, availability windows, and use cases. For a one-parameter read-only tool, this is comprehensive and leaves no critical 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 covers the single 'window' parameter with a description that already explains the enum values and their implications ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description merely lists the windows without adding further semantic nuance, so it adds little beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now.' It then details the exact outputs ('top tools, top packs, and total call volume') and window options. This distinguishes it from siblings like discover_tools or ask_pipeworx by focusing on aggregate usage trends rather than discovery or Q&A.

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 'Useful for:' section provides three explicit use cases, such as 'discovering what data sources are hot for current events' and 'confirming a popular tool is the canonical choice before asking your own question.' This gives clear context for when to use the tool, though it does not explicitly state when not to use it or name alternative tools.

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

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

The description extensively discloses behavior beyond the annotations: it details the output structure, the Jaccard similarity threshold (≥0.30), the placeholder filter (>20% causes null), and the fill-check logic with the warning 'do not trade it' when realizable_edge_pp ≤ 0. It adds rich context about how the tool handles edge cases and failed scans.

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 (~200 words) but well-structured with bolded section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds non-redundant operational detail, and the organization makes it scannable. It is slightly verbose but appropriate for the tool's complexity.

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

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

Despite having no output schema, the description covers return fields for all modes, error/edge cases (skipped_low_similarity, placeholders_filtered), and interpretation guidance (realizable_edge_pp). It fully explains the tool's behavior in every mode and parameter combination, making it self-contained.

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

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

Although the schema already includes descriptions for both parameters, the tool description adds substantial meaning: it explains what an event slug looks like, how it differs from topic, and how the tool processes each. For example, it mentions that topic mode 'searches related events across the platform, flattens markets, runs the comparator on the union' – far more useful than the schema's brief descriptions.

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

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

The first sentence clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This is a specific verb-resource-method combination that distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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 explains when to use each invocation mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It even recommends 'event (recommended for a specific market)' and points to an alternative tool for custom sizing: 'use polymarket_fill_risk.' This gives clear usage boundaries.

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

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

Annotations already carry readOnly/idempotent hints. Description adds caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure with diagnostics to explain empty segments, filtering heuristics (placeholder-slug filter, >20% placeholder skip), and caveats like the unreliable Fed signal without paid data. This far exceeds annotation coverage.

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

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

The description is front-loaded with a clear purpose and uses ALL-CAPS section markers for scannability. It is quite long (500+ words) and contains some arguably irrelevant detail ('Run 8 from prior 85%/5%/50:1'), but the complexity of the tool (9 knobs, 3 segments) justifies the thoroughness.

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 documents the response top-level (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and explains why segments may be empty. It also covers caching and practical filters, making it a complete manual 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 covers 100% of 9 parameters with detailed descriptions and examples. The description adds a high-level grouping of knobs ('TRADEABLE-EDGE KNOBS') but repeats information already in the schema (e.g., min_partition_leg_kelly's design caveat appears in the schema too). No new syntax or semantics beyond schema.

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

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

The first sentence clearly states the verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes from siblings by framing the use case ('what should I bet on today') and listing three response segments, setting it apart from tools like polymarket_arbitrage.

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

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

The description explicitly scopes use to opportunity discovery ('agents discover opportunities without paging hundreds of markets') and provides detailed guidance on knob usage (e.g., 'Set to 2 to require tight books'). It does not explicitly name alternative tools or exclusions, but the context is clear enough for an agent to decide when to invoke.

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

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

The description goes far beyond the annotations by disclosing data limitations (60-day TTL, snapshot gaps on cache-miss), computational details (decay from daily closes, not intraday), and semantic nuances (negative edge_pp_net means SELL YES). It also explains response semantics like 'expired' and 'snapshot_dates'. This is rich behavioral context that annotations alone do not 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 well-structured and dense with information. It opens with a clear purpose, then covers args, response structure (with uppercase labels), and limitations. Every sentence contributes useful context, and the RESPONSE/LIMITS sections make it easy to scan.

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

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

With no output schema, the description fully explains the return format (tracked, expired, snapshot_dates) and key metrics. It also covers edge cases like snapshot gaps and history depth. The tool's complexity is high, and the description adequately addresses both usage and data quality caveats.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates defaults and bounds for days and window, matching the schema. It introduces the term 'snapshot family' for window, but the schema already conveys this. No new parameter meaning is added beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers a specific question, 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings by referencing 'daily polymarket_edges snapshots', implying an analysis layer on top of the current edge data.

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

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

The description provides clear context for when to use the tool (to analyze edge persistence and decay across historical snapshots), and implicitly contrasts with the sibling 'polymarket_edges' by explaining this is built from its snapshots. However, it does not explicitly state when not to use it or name alternative tools for other scenarios.

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

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

Annotations already mark the operation as read-only and idempotent, and the description adds substantial behavioral context: it walks the order book ladder, returns verdicts, lists per-leg fill details, and highlights the key risk that partial basket fills convert an arb into an unhedged directional position. This goes well beyond the structured annotations.

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

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

The description is long but highly structured with labeled sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence carries useful information, and the critical usage guidance is front-loaded. The format mirrors the two-mode complexity of the tool without unnecessary fluff.

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

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

With no output schema, the description thoroughly enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers risk implications and parameter defaults, making it complete for a tool of this complexity.

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

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

Although the input schema already provides 100% parameter coverage, the description adds operational meaning: size_usd means max spend on buys but target proceeds on sells, basket size_usd is settlement notional per share, and market/event are mutually exclusive modes. This is valuable 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 opens with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' a specific verb+resource statement. It clearly distinguishes itself from siblings by naming polymarket_arbitrage and polymarket_edges and explaining its role as a pre-trade risk check.

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?

Contains an explicit 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' directive. It also explains when to use single-market vs basket mode and warns against acting on thin books, providing clear usage context.

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

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

Annotations already mark it read-only/idempotent/non-destructive; the description goes further by explaining compatibility warnings/codes, the unclassified-leg exclusion rule, skipped counters, and temporal alignment. This is substantial behavioral disclosure beyond annotations, with 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 front-loaded, with the core definition in the first sentence and labeled mode/safety/response sections after. Some sentences are long and could be bulleted, but every sentence carries needed operational detail for a complex comparison tool.

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

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

With no output schema, it inventories the response: leg prices, top_spreads_pp, compatibility fields, temporal_alignment, skipped counters, and low_confidence_pairs. It also warns about tradeability and the meaning of pre-mapped pairings, so an agent has enough to interpret results safely.

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

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

Schema covers all 3 params with descriptions and examples, so baseline is 3. The description adds mode-level rationale and override semantics, but the key override behavior is already in the schema, so it doesn't lift the score higher.

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 concrete definition: it reports the cross-venue spread between Kalshi and Polymarket for the same resolving question, then details two invocation modes. This clearly distinguishes it from Polymarket-only siblings by naming both venues and the outcome-matching logic.

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

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

It clearly separates two usage modes: use `topic` for 10 pre-mapped macro shortcuts and explicit ticker/slug for custom pairings, plus a warning that pre-mapped topics often carry compatibility warnings. It doesn't name sibling alternatives or say when not to use the tool, so it earns 4 rather than 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds the return item structure and optional filter behavior, which go beyond the annotations and schema.

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

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

The description is two succinct sentences that front-load the core action, then provide output details and optional filtering. No waste or redundancy.

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

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

For a simple read-only tool with strong annotations and complete schema coverage, the description adequately explains the return format and filtering capability. It does not mention pagination or error handling, but these are minor gaps given the tool's simplicity and the presence of a 'limit' parameter in the 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 coverage is 100% with descriptive parameter entries for feed, limit, and query. The tool description reiterates the feed id and keyword filter but does not add significant new meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool reads a curated crypto feed by id, specifies the output as normalized items with fields (title, link, published, summary), and references list_feeds as the source of feed ids. This distinguishes it from siblings like fetch_feed by emphasizing 'curated' and 'normalized'.

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 context that the feed id comes from list_feeds and mentions optional keyword filtering, implying a workflow of first listing feeds then reading one. It does not explicitly name alternatives or exclusions, but the context is clear enough for a read 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, covering the safety profile. The description adds valuable behavioral context: scoping to user identifier (anonymous IP, BYO key hash, account ID) and the list-all behavior when key is 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?

Three sentences, each with a distinct job: stating the core action, giving examples of use cases, and explaining scope and related tools. No fluff; information is front-loaded and well organized.

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-optional-parameter tool with strong annotations, this description covers purpose, usage, scope, and sibling relationships adequately. No output schema exists, but return format is not needed for such a straightforward retrieval tool.

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

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

Schema description coverage is 100%, so the schema already documents the key parameter and the omit-to-list behavior. The description reinforces this but does not add new parameter-level semantic detail beyond what the schema provides.

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

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

The description clearly states the two behaviors: retrieving a value by key and listing all keys when key is omitted. It identifies the resource as the agent's saved memory and distinguishes from sibling tools like remember and forget by explicitly pairing with them.

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

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

Provides clear usage context ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and names related tools for save/delete. However, it does not explicitly state when not to use this tool versus alternatives, so it stops short of a full 5.

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

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

Annotations claim readOnlyHint: true, but the description explicitly states that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones', which is a persistent state change. This directly contradicts the readOnlyHint annotation, making it an annotation contradiction. Despite the description being transparent about the side effect, the inconsistency with the annotation degrades transparency to the minimum.

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 that front-load the core purpose, then pack in return data anatomy, filtering options, side-effect semantics, and even an alternative integration point. Every sentence earns its place with no filler or redundancy.

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

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

For a tool with no output schema, the description provides a solid mental model of what is returned (source, citation_uri, raw payload), explains the polling-friendly nature, and covers the main parameters' behavior. It also acknowledges the same feed's HTTP endpoint, giving context for alternative use cases. The only gap is not clarifying the relationship to read_feed/fetch_feed, but that's not essential for this tool's operation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value beyond the schema by giving a concrete example for type ('sec_8k'), clarifying the format and effect of 'since' (ISO timestamp, fired_at >=), and explaining the functional consequence of mark_read:true. This enhances understanding without repeating schema 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 opens with 'Pull fired events from your subscription feed', a specific verb+resource that clearly states the tool's purpose. It distinguishes itself from sibling tools like fetch_feed and read_feed by focusing on 'recent alerts' and the evaluator's persisted feed, with details like citation_uri and mark_read.

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: it's for polling recent alerts, mentions filtering by type/since, and even offers an alternative access method via GET URL for scripts. However, it does not explicitly contrast with sibling tools like fetch_feed or read_feed, omitting direct when-to-use versus alternatives 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?

Beyond the annotations (read-only, idempotent, non-destructive), the description reveals rich behavioral details: it fans out in parallel to three APIs, handles GDELT→GNews fallback on rate limits, discloses USPTO PatentsView sunset and soft-fail behavior, and describes the output structure (changes[] grouped by source + total_changes + citation URIs). This gives the agent a clear picture of side effects, failure modes, and return shape.

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 clause contributes actionable information: examples, data sources, fallback logic, parameter syntax, return value, and a pointer to an alternative tool. It is front-loaded with user intent and structured logically, earning a top score for conciseness and structure.

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

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

Given the tool's complexity (multiple APIs, fallback logic, date-range handling) and absence of an output schema, the description is remarkably complete. It explicitly states what is returned (structured changes[] grouped by source + total_changes + URI citations) and covers edge cases (rate limits, API sunset), so an agent can confidently decide to use it and understand its behavior.

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 (type enums, since format, value format). The description mostly restates the `since` format and adds a 'typical monitoring' recommendation, but it does not add significant new meaning beyond the schema. Therefore the baseline of 3 is appropriate; the schema does the heavy lifting.

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

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

The description opens with natural-language examples that capture the tool's intent, then defines it precisely as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists concrete data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes from the sibling tool entity_profile, so purpose is unambiguous and well-differentiated.

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 guidance on when to use this tool versus alternatives: 'Use entity_profile instead when you want the static profile... regardless of window.' It also recommends typical values for the `since` parameter ('Use 30d or 1m for typical monitoring') and explains fallback behavior for GDELT/GNews, so the agent knows exactly when and how to invoke it.

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

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

Beyond annotations (which already indicate idempotency and non-destructiveness), the description adds valuable behavioral context: key-value scoping by identifier, retention details (persistent for authenticated users, 24 hours for anonymous), and pairing with recall/forget. This goes beyond what annotations provide, though it does not clarify overwrite behavior for existing 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 three sentences with no fluff. It front-loads the core purpose, then gives usage guidance, then covers storage behavior and related tools. Every sentence earns its place and the structure is logical.

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

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

Given the tool's simplicity (2 required parameters, no output schema) and the strong annotations, the description is complete. It covers what to save, when to save, how storage works, and how to retrieve/delete later, leaving no significant gaps for an agent to use the tool correctly.

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

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

The input schema already provides 100% coverage with descriptions for both key and value, including examples. The tool description reinforces the purpose but does not add new parameter semantics beyond what the schema already explains, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Save data') and resource ('memory'). It distinguishes from siblings by explicitly mentioning recall and forget as complementary tools, making its role unique among the sibling tools.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') with concrete examples. It mentions alternatives (recall, forget) but does not explicitly state when not to use it, though the 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 readOnly, idempotent, and non-destructive hints. The description adds significant behavioral context: cascading through multiple lookup endpoints, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR still returns), explicit reporting of unresolved identifiers, and replacing 2-3 manual lookups. This exceeds 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, starting with examples, then core purpose, usage instruction, and detailed type breakdown. It is longer than necessary but every sentence adds value. The front-loading of example queries is effective. Minor trimming could improve conciseness.

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

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

Given the tool's complexity (multiple data sources, graceful degradation, no output schema), the description provides a good picture of what to expect: identifiers with source labels and an explicit unresolved field. It does not describe the exact output format, but the agent can infer the structure from the examples. Slightly more detail on the response shape would push this to 5.

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

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

Although the input schema has 100% description coverage, the description adds substantial value: it explains the meaning of value for each type (ticker, CIK, name for company; brand or generic for drug), details the behavior for ISIN inputs, and clarifies that the tool accepts various input formats. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to canonical/official identifiers needed by other tools. It provides specific examples and lists supported entity types (company, drug), making the verb+resource identity explicit. While it does not explicitly differentiate from siblings like entity_profile, the unique function of name-to-ID resolution is unmistakable.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' establishing a clear priority and context for use. It does not, however, provide explicit when-not-to-use scenarios or compare with sibling tools, which prevents a 5. The guidance is sufficient for most agents.

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 beyond that by explaining the tool probes each entity via ai_visibility_check, ranks results, and returns a structured list (score, confidence, signal density). This gives the agent a clear model of what happens internally, though it doesn't cover error/rate-limit edge cases.

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 main purpose and followed by a concrete example. Every sentence adds value—methodology, use case, and return format—with no repetition of schema details. It is an exemplar of concise, structured writing.

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 (multi-entity comparison, ranking, no output schema), and the description compensates by detailing the return format (score, confidence, signal density) and the internal probing mechanism. It stops short of describing model selection or API key behavior, but those are fully covered in the schema, so the description is sufficiently complete 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?

The input schema covers all four parameters with descriptions, including entity precedence (first entry as subject) and model selection. The description adds little beyond the schema, only noting that it probes each entity with ai_visibility_check, which is already implied. Baseline 3 is appropriate for full schema coverage with no enum constraints.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing this from the sibling single-entity ai_visibility_check. It also states the tool ranks by score and surfaces most/least recognized, giving a precise picture of what it does.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') with an illustrative query, making it clear when to use this tool. It does not explicitly list alternatives or exclusions, but the context strongly implies comparison scenarios, so it earns a 4 rather than 5.

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

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

The description discloses behavioral traits beyond the annotations, including partial failure degradation ("sources_failed will list it if it times out"), the 5-30s first-measurement latency, and the fact that the tool fans out across two external services. These details provide a richer mental model for runtime behavior.

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

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

The description is information-dense and well-structured, opening with the concrete purpose and then layering usage, output fields, ecosystem constraints, and failure behavior. Every sentence earns its place without redundancy.

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

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

Given the tool's multifaceted nature, the description covers all necessary context: use cases, exact return fields, ecosystem limitations, latency caveats, and graceful degradation. It is self-sufficient even without an output schema.

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

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

The input schema already provides complete descriptions for both parameters (package name, optional version) with 100% coverage. The description does not add additional parameter-specific detail, so the baseline of 3 applies.

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

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

The description explicitly identifies the tool as a composite "should I add this npm package" check across deps.dev and bundlephobia, listing specific data sources and output fields. This clear verb-resource-purpose effectively distinguishes it from other research tools.

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

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

The description gives explicit usage triggers ("Use whenever an agent asks...") and an explicit exclusion for non-NPM ecosystems, pointing to an alternative ("deps.dev:version directly"). This is ideal guidance for choosing when to invoke the tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the safety profile is established. The description adds significant beyond-annotation behavior: BGE-base-en embeddings, 500-char overlapping windows, cosine similarity, character offsets, and truncation at 200K chars with a flag. This is rich, useful context for an agent.

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

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

Four dense sentences, each earns its place: the first states the action, the second describes the interface, the third gives usage guidance, and the fourth discloses technical details. Front-loaded with the core purpose and no 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?

Despite having no output schema, the description explains return values (top-N passages with character offsets and similarity scores), mentions the limit range (1-20, default 5), and covers truncation behavior. It also positions the tool within a workflow with ask_pipeworx_grounded, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by framing 'text' as 'the text you already pulled,' giving example queries for 'query,' and explaining that 'limit' controls the 'top-N passages.' While not exhaustive, it enriches the parameter semantics.

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

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

The description uses a specific verb and resource: 'Semantic search INSIDE a fetched record,' immediately differentiating it from siblings. Concrete examples (SEC 10-K, article, long tool result) make the purpose unmistakable. It also contrasts with ask_pipeworx_grounded by focusing on searching within already-pulled text.

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

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

It explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides an alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives the agent clear decision 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 indicate non-read-only, non-destructive, idempotent, and open-world behavior. The description adds substantial context: the requirement for OAuth, details on supported event types, SMS verification and caps, webhook signing and auto-disable after 10 failures, and the return of a subscription id. This goes well beyond the annotations and fully discloses important behavioral traits.

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

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

The description is long but dense with relevant information, structured into supported types and delivery channels. It front-loads the core purpose and uses concise lists. While some might consider it verbose, every sentence delivers necessary detail, making it efficient rather than bloated.

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 nested objects and no output schema, the description is remarkably complete: it states the return value, prerequisites, per-type parameter examples, delivery channel behavior, and operational limits. It equips an agent to select and invoke the tool correctly without needing additional 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?

The input schema already covers all parameters with detailed descriptions (100% coverage). The description adds practical meaning, such as interpreting items:["5.02"] as officer changes, explaining the SMS 10/day cap, and noting the webhook signing secret is returned once. These examples and clarifications enhance understanding beyond the schema, though the high schema coverage means extra credit is modest.

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

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

The description begins with a specific, action-oriented statement: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly identifies the tool's purpose and distinguishes it from siblings like unsubscribe, list_subscriptions, and recent_alerts. It further specifies supported subscription types, making the scope 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 use context, such as requiring a Pipeworx OAuth account and noting that anonymous/BYO users cannot persist subscriptions. It also explains delivery channels and when to use them, referencing alternatives like pulling via recent_alerts. However, it does not explicitly contrast with list_subscriptions or unsubscribe, though the purpose is clear enough to infer appropriate usage.

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 convey read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail: it returns category-bucketed example questions with exact tool+argument shapes, and dynamically pulls from the live catalog. No contradictions with annotations.

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

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

The description is dense but well-structured, front-loading the purpose and then explaining behavior and usage. Every sentence adds value, though it is slightly longer than necessary.

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 low complexity and the absence of an output schema, the description fully covers what the tool returns, how to invoke it, and when to use it. It also contextualizes the tool among meta-tools, making it complete 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 covers 100% of the parameter, but the description enriches it by listing example topic values (finance, pharma, betting) and clarifying that omitting topic yields a cross-category spread. This goes beyond the schema's simple type/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 explicitly identifies the tool as 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It uses a clear verb+resource structure and distinguishes itself from siblings by focusing on generating example questions and mapping them to tools, unlike search or research tools.

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

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

Provides direct guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit or pass the topic parameter, giving clear contextual triggers.

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 significant behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical events via recent_alerts. This clarifies the tool's side effects and non-obvious behavior, which is valuable for an agent.

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

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

The description is a concise two sentences. The first states the action and ownership rule; the second explains the deactivation behavior and its consequence. Every sentence contributes meaningful 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 the tool's simplicity (one parameter, no output schema) and strong annotations, the description provides enough context: key behavioral traits are covered, and the linkage to recent_alerts completes the operational picture. No critical information 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 input schema fully documents the single parameter id with a clear description ('Subscription id (uuid) returned by subscribe'), so the schema already carries the semantic weight. The description only mentions 'by id' and adds no additional parameter details, justifying the baseline score of 3.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the cancellation action and ownership enforcement.

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 clear context by stating ownership restrictions and the soft-delete behavior, which helps an agent understand when to use this tool (to cancel own subscriptions). It also mentions recent_alerts as the place where historical events remain available, giving a useful pointer for follow-up actions. However, it doesn't explicitly state when not to use it compared to alternatives.

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

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

Annotations already provide read-only/idempotent safety context, but the description goes further by disclosing failure semantics: 'could_not_verify' means the check did not happen and must not be treated as evidence, while 'unsupported' means no source exists. It also reveals internal routing and replacement of multiple sequential calls, adding substantial behavioral transparency.

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

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

Although long, the description is front-loaded with trigger phrases, followed by usage, pipeline, return values, critical caller warnings, and efficiency rationale. Every sentence contributes essential information for correct invocation and interpretation, and the structure makes it easy to scan.

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

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

With no output schema, the description compensates by listing all verdict values, explaining 'could_not_verify' and 'unsupported' distinct failure modes, mentioning the actual value plus citation, and covering both financial and non-financial claim processing. It is comprehensive enough for an agent to confidently 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?

Schema coverage is 100% with detailed descriptions for both parameters, so the schema carries the primary meaning. The description adds slight reinforcement about tolerance overriding claim wording and the hallucination-detection use case, but it does not significantly expand beyond what the schema already states—hence the baseline 3.

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

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

The description explicitly identifies the tool's purpose as natural-language claim verification, with trigger phrases like 'fact check' and 'verify the claim that…'. It clearly distinguishes this from sibling research/Q&A tools by emphasizing verdict output and the specific two-path processing (SEC EDGAR for financial claims, grounded pipeline for all others).

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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' which gives a clear context. It also explains the scope of financial versus non-financial claims, but it does not explicitly name sibling alternatives or exclusion criteria, leaving some room for ambiguity with tools like ask_pipeworx_grounded.

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