econdata

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description adds meaningful context: the default model and its cost (free), the BYO-key flow where users pay Anthropic directly, and the per-model return structure. It does not disclose rate limits or error behavior, but the added cost and key-handling details justify a 4.

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: the first states purpose and output, the second explains model selection and key handling, the third lists use cases. Every sentence earns its place, information is front-loaded, and there is no redundancy or fluff.

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

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

Given no output schema, the description compensates by summarizing the return shape (per-model {score, confidence, signals, raw_response} plus combined view). It covers core usage, cost, and use cases. However, it does not explain what 'score', 'confidence', or 'signals' mean or how to interpret them, leaving a minor gap for such a tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor value by noting the default model (`workers-ai`) and that `_apiKey` is needed for Anthropic, but these largely mirror the schema descriptions. No significant extra meaning is provided for `entity` or `context`.

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

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

The description clearly states the tool's function: probing LLMs for knowledge about an entity and producing a 0-100 visibility score per model. The verb 'probe' and specific output (score, confidence, signals) strongly convey purpose. However, it does not differentiate from the sibling tool 'scan_competitor_ai_presence', which likely overlaps in function, so it misses the explicit sibling differentiation needed for a 5.

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

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

The description provides clear use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to pass `_apiKey` (to include Anthropic) and notes the free default. Yet it does not offer explicit when-not-to-use guidance or mention alternative sibling tools, stopping short of a 5.

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

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

Annotations already mark the tool as readOnly, idempotent, open-world, and non-destructive. The description adds useful behavioral context: it auto-routes to thousands of tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. There is no contradiction with 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 front-loaded with the main directive ('PREFER OVER WEB SEARCH') and organized into use cases, examples, and alternatives. Some redundancy exists in the extensive example list, but most content 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?

Covers what the tool does, which inputs trigger it, what output it returns, and which sibling to use instead for broad/multi-part queries. For a general question router with no output schema, this is a complete and actionable description.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the same natural-language question field. The description contributes no additional per-parameter semantics beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description states a clear routing/search behavior: 'Routes the question to the right one of 5,798 tools...' and mentions it returns structured answers with pipeworx:// citation URIs. It identifies the tool's role as a question router, but it does not explicitly differentiate from sibling variants ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' for many topic categories and 'Use whenever the user asks...' with example phrasings. It also names an alternative for broad/multi-part questions ('use deep_research') and notes that live news is already covered, giving an agent clear selection criteria.

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 read-only, idempotent, and non-destructive signals. The description adds meaningful behavioral context: candidate routing improvements are enabled live when under test, no candidate is active as of a specific date, the response shape is identical to ask_pipeworx, and results are compared against the stable router. This goes well beyond the structured 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 moderately long but every sentence earns its place: identity, current status, usage direction, and experimental nature are all covered without fluff. Critical information like 'no candidate active right now' is front-loaded in the first sentence.

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

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

For a simple one-required-parameter tool with rich annotations and no output schema, this description is complete. It explains what the tool is, what it does, how it differs from siblings, when to use it, and its current operational state. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents the question parameter and its aliases. The description mentions 'same arguments' as ask_pipeworx but adds no parameter-level semantics beyond what the input schema provides, so the high-coverage 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: a beta universal router identical to ask_pipeworx with candidate routing improvements. It clearly distinguishes itself from ask_pipeworx and ask_pipeworx_grounded by framing it as the experimental edge, while explaining that no candidate is currently active so it matches ask_pipeworx exactly.

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

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

The description explicitly tells the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the relationship to the stable router and clarifies that this is a full working router, not a stub or fallback-only tool.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses that answers are extracted only from tool results, that refusals occur with specific reasons, and that it costs an extra LLM call. It also enumerates the refusal_reason enum, giving strong transparency into failure modes.

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

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

The description is information-dense but well-structured, front-loading the core purpose and then layering usage, return format, and cost tradeoff. It is longer than minimal, but nearly every sentence adds operational value and no sentence is 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?

With no output schema present, the description compensates thoroughly by specifying the success response fields, the refusal response variants, and the exact refusal_reason values. Combined with full schema coverage for the input, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema coverage is 100% and the schema fully documents the single meaningful parameter with aliases. The description adds no additional parameter-level details, but that is acceptable because the schema carries the burden.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with a specific verb/resource relationship and explicit distinction from ask_pipeworx. It states what the tool does, the exact return shape, and when it should be preferred, making sibling differentiation immediate.

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 this tool when an answer will be quoted, cited, or acted on and facts must not be invented, and explicitly recommends ask_pipeworx for casual lookups due to the extra LLM call. This gives agents a clear decision rule and names the alternative.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds a wealth of behavioral detail beyond that: low-confidence matches short-circuit with status:'low_confidence_match', closed markets return a blocking status, wide spreads carry tradeability:'illiquid_wide_spread', and cancellation rules are parsed and flagged for EV risk. These are critical, non-obvious behaviors the agent would not know otherwise.

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 very long, but it is well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) and front-loaded with the core purpose. Each section carries unique operational details, so it earns its length, though it could be trimmed to avoid overwhelming agents.

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

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

Since there is no output schema, the description must explain return values, and it does: result.market fields, result.analysis fields, result.evidence keying, the resolver contract with match confidence/alternatives/suggestions, parent_event extractor, news fallback fields, and cancellation-rule semantics. It also covers edge cases like closed markets and wide spreads, making the tool self-explanatory for correct invocation.

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

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

The schema already covers all three parameters (100% coverage), so the baseline is 3. The description adds value by reinforcing the market input formats (slug, URL, or question text) and providing fan-out examples that show how market content influences the actual data packs used, which helps the agent predict parameter effects beyond the schema definitions.

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 states exactly what the tool does: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It names the specific verb, resource (Polymarket bet), and scope, and the use-case strings ('should I bet on X', 'what does the data say about Y') clearly distinguish it from sibling Polymarket tools like arbitrage or edge trackers.

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 has an explicit 'Use for' line with example queries and a fan-out examples section that shows when to expect certain data sources (BTC bet → coingecko+fred, Fed bet → fred+kalshi_macro, etc.). It does not explicitly say 'do not use when...' or name alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description adds substantial behavioral context beyond these: it discloses data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, cash, debt, adverse-event counts), fiscal-year handling, sorting behavior, and citation URIs in the response. This is rich contextual disclosure that complements 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 average but every sentence supports the agent's decision-making. It front-loads the trigger phrases and purpose, then provides necessary data-source and output details. It is dense but not wasteful, earning a 4 rather than a 5 for being slightly verbose.

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

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

Given no output schema, the description explains what is returned (paired data + citation URIs), how results are sorted, and what data each type pulls. It also mentions the off-calendar fiscal-year handling, which is a subtle correctness detail. This is sufficient for the agent to understand the tool's full behavior in its context.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains what each type value retrieves (company financials vs. drug counts), gives concrete examples for values, and clarifies the 2–5 entity count and ticker/CIK format. This goes well beyond the schema's basic descriptions.

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

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

The description opens with concrete trigger phrases and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile by emphasizing parallel comparison and the specific data pulled for each type.

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

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

It provides explicit when-to-use guidance with example query patterns, and explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent when to choose this tool and what to avoid (sequential lookups), satisfying the when/when-not criteria.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: parallel decomposition across 5,798 tools, findings packet contents, gaps[] never invented, contradictions[] behavior, semantic excerpting, resolvable citations, and latency expectations. No contradiction with annotations.

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

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

The description is long, but the tool is complex and every section earns its place: auth, alternatives, scope, mechanics, return format, gaps, contradictions, and timing. It is front-loaded with the most decision-critical facts (account requirement and the ask_pipeworx alternative). Slight redundancy in the depth explanation keeps it from a 5.

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

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

Given two parameters, no output schema, and a complex research tool, the description covers everything an agent needs to call it correctly: auth requirements, tiering, data scope, return packet structure, gap handling, contradiction reporting, citation resolvability, and expected latency. Example questions further anchor correct usage.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining the practical consequences of depth choices: paid requirement for thorough, latency ranges, and which depth tiers include contradiction scans. It also clarifies that the question parameter is well-suited to multi-part natural language. This adds genuine operational meaning beyond the schema.

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

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

The description uses a specific verb-resource pair — 'grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' — and clearly distinguishes itself from open-web search. It also names what it is not and references a sibling (ask_pipeworx) to prevent confusion.

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

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

The description explicitly states when to use the tool ('best for broad/multi-part questions over structured data'), when not to use it ('For a single lookup use ask_pipeworx instead'), and the account/paid-tier prerequisite. It even gives a fallback: if not signed in, use ask_pipeworx.

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, so the safety profile is covered. The description adds valuable behavioral context by disclosing that results include full input schemas with curated examples and are ready to call directly, eliminating a second schema lookup. It also advises calling this tool first, which is a useful process hint. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and includes a comprehensive list of domains, which is informative but slightly lengthy. The structure flows logically from purpose to usage to return details to strategic advice. Every sentence contributes value, though the domain enumeration could be trimmed without losing essential meaning.

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

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

The description adequately covers the tool's role as a discovery mechanism, listing covered domains, return details (top-N tools with schemas and examples), and the recommendation to use it early in the exploration process. Given there is no output schema, the description does not need to detail return structures. Minor omissions like pagination or query phrasing guidance are compensated by the schema examples and the overall clarity.

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% per context signals, so the schema fully documents all six parameters, including aliases for 'query' and the 'limit' parameter. The description adds minimal parameter semantics beyond the schema, only implicitly referencing the query via 'describing the data or task' and the limit via 'top-N'. This matches the baseline of 3 for high 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 clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates the covered domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling tools by acting as a discovery layer rather than a domain-specific data retrieval tool. The verb 'find' and the resource 'tools' are specific and unambiguous.

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

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

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates when to use the tool and contrasts with using specific tools for direct answers, fulfilling the 'when/when-not' requirement.

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

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

Annotations already mark it read-only and idempotent, and the description adds significant behavioral context: sources_used/sources_failed indicate actual data availability, empty sections are real 'no data' not bugs, the patent source soft-fails after its sunset, and private companies return resolved:false with notes. No contradiction with annotations.

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

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

The description is long, but the tool is complex and almost every sentence carries operational detail. It is well front-loaded with purpose and usage, though it mildly repeats parameter-shape facts already present in the schema.

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

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

With no output schema, the description carries the full burden of explaining return values and does so thoroughly: each profile section, URI format, empty-section expectations, failure modes, and resolution behavior are described. An agent has enough context to call the tool and interpret results correctly.

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

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

Although the schema already covers the two parameters, the description adds actionable semantics: value can be a ticker, zero-padded CIK, or company name; type values are interchangeable; names resolve via SEC EDGAR; and private companies produce a specific resolved:false outcome. This goes well beyond the schema in preventing misparameterization.

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 clearly that this returns a 'full cross-source profile of a US public company' in one parallel call, with concrete example queries like 'Tell me about X' and 'brief me on Tesla'. The 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' line differentiates it from narrower lookup tools.

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

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

Provides explicit usage triggers via example query phrasings and a clear preference rule for holistic-view requests. However, it does not contrast itself with broader sibling research tools like deep_research or compare_entities, so some alternative-selection guidance is missing.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description restates the delete behavior but adds little beyond the annotations, such as what happens if the key does not exist or any permission requirements. It does not contradict annotations, but also does not enrich the behavioral profile significantly.

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

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

The description is two sentences long, front-loaded with the primary purpose, and each sentence serves a distinct function: stating what it does and when to use it. No redundant or filler content.

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

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

For a simple single-parameter destructive tool with annotations covering idempotency and destructiveness, the description supplies usage scenarios, cross-references sibling tools, and the schema fully defines the input. No output schema is necessary, making the description complete.

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

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

The input schema covers 100% of the parameter with a clear description ('Memory key to delete') and an example. The tool description does not add additional meaning beyond the schema, which is adequate but not extra.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource. It distinguishes itself from sibling tools like remember and recall by naming the deletion operation and explicitly referring to 'memory' as the object.

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' This gives clear guidance on when to use this tool versus alternatives, and even suggests pairing with remember and recall.

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

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

Annotations already declare readOnly and idempotent behavior. The description adds valuable behavioral context: it fetches the page, extracts specific elements, and emits a standard markdown format, plus output is a text blob for site-root placement. 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?

Description is front-loaded with the main action, followed by process, output, and use cases in four tight sentences. Every sentence earns its place with no redundant filler.

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

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

Tool is simple (2 params, no output schema). The description covers purpose, process, output format, and practical use cases, making it complete for an agent to understand what the tool does and what it returns.

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

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

Schema description coverage is 100%, so the schema fully documents url and max_links. The description does not add extra parameter details beyond reinforcing that url is any site URL and max_links relates to link entries, which is already in the schema.

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

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

Clearly states the tool generates a production-ready llms.txt file for any URL, explicitly describing the process (fetch, extract, emit markdown) and differentiating from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation.

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

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

Provides explicit use cases (indexing a client's site, drafting for own project, auditing competitor) which give clear context. However, it does not explicitly state when NOT to use this tool or directly mention alternative sibling tools, so it lacks exclusions.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral details: it defaults to the NSA series, explains the SA alternative, notes the ~1 point difference, and promises that the answer states which adjustment was used. This goes well beyond the annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the primary purpose, then details the return payload, default series, the SA option, and the adjustment disclosure. No unnecessary words.

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

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

With an output schema present, the description still covers the essential call-time knowledge: what the tool returns, the default behavior, the seasonal adjustment option, and the impact of the chosen series. Nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the seasonally_adjusted parameter's meaning (NSA vs SA series, BLS/FRED equivalents), but does not add new parameter-level semantics beyond what the schema already provides.

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

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

The description clearly identifies the tool's function: returning the current US inflation rate and CPI-U history for All Urban Consumers. It specifies the exact resource (monthly index values) and the computed metric (yoy_inflation_pct), which is distinct enough even among sibling data 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 concrete use cases: it directly answers 'what is the latest inflation rate' and 'what is the current CPI-U index level.' It also explains when to set seasonally_adjusted to true. It does not explicitly name alternative tools or say when not to use it, but the context is clear.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that by specifying that the returned employment figures are in thousands and organized by period. It does not disclose rate-limit or auth details, but those are partially covered by the _apiKey parameter and annotations.

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

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

The description is a single efficient sentence that front-loads the action and resource. Every word contributes meaning, with no filler, repetition, or unnecessary qualification.

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, rich annotations, full schema coverage, and an output schema, the description covers the essential information an agent needs. Minor gaps like explicit range defaults or revision behavior are not critical because the schema and output schema already provide sufficient detail.

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 parameters are already fully documented. The description's mention of example industries mirrors the schema's existing enum and adds no new semantic information about how parameters interact or behave.

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

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

The description states a specific verb ('Get'), a precise resource ('US non-farm payroll employment by industry'), and the output unit ('in thousands by period'). This clearly distinguishes it from sibling economic tools like get_unemployment and get_cpi by focusing on employment broken down by industry.

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: any query needing US non-farm payroll employment figures for a specific industry. It does not explicitly name alternatives or exclusion criteria, but the scope is specific enough that an agent can select this tool confidently without confusion.

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, and idempotentHint, so the safety profile is covered. The description adds value by specifying the return shape ('historical data points with dates and values') and giving recognizable examples, which helps an agent anticipate behavior. No contradiction with annotations.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the examples are compact and illustrative. Every part of the description 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 a rich schema, annotations, and an output schema, the description covers what an agent needs to safely call the tool. The main missing elements are explicit routing to siblings and default date-range behavior when start_year/end_year are omitted, but these are not critical given the existing structure.

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

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

Input schema coverage is 100%, with each parameter already described in full, so the baseline is 3. The description adds helpful real-world series ID examples but does not add meaning beyond the schema for start_year, end_year, or _apiKey.

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 ('Fetch'), a resource ('economic time series'), and the key selection mechanism ('by ID'). Concrete examples of well-known series IDs make it immediately clear what the tool does and distinguish it from specialized siblings like get_cpi and get_unemployment.

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

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

The description implies through 'any economic time series by ID' that this is the general-purpose tool, while siblings like get_cpi are specialized. However, it never explicitly says when to prefer this tool over the convenience siblings, and there is no when-not guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and a non-destructive nature. The description adds useful behavioral context beyond that: it describes BLS as the data source, the civilian unemployment rate as the metric, and monthly granularity over time. 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?

Two tight sentences: the first states the core purpose and metric, and the second gives query-language guidance plus return frequency. No filler or redundancy.

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

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

For a simple, read-only tool with all parameters optional and fully described, an output schema present, and annotations covering safety behavior, the description is complete. It gives the data source, the exact metric, queried phrasing, and the output granularity.

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

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

The input schema has 100% description coverage: _apiKey, start_year, and end_year each have meaningful descriptions. The tool description adds little about parameters, so the baseline score of 3 is appropriate; it does not need to repeat schema content.

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 names a precise verb ('Get'), a specific resource ('US civilian unemployment rate'), a data source ('Bureau of Labor Statistics'), and the exact metric ('percentage of the labor force currently unemployed'). This clearly distinguishes it from related tools like get_cpi or get_employment_by_industry.

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 for 'unemployment rate' / 'jobless rate' queries, which gives clear context for when this tool is appropriate. It does not name sibling alternatives or state exclusions, so it stops short of the strongest guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by specifying it returns 'active subscriptions' by default and listing the response fields, which goes beyond annotations. It doesn't mention pagination or rate limits, but the annotation coverage lowers the burden.

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 core purpose, followed by return fields and a clear usage directive. Every sentence earns its place with no redundant fluff.

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

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

For a simple list tool with one optional parameter, the description covers purpose, return fields, and usage. The annotations cover safety, and the schema covers parameters, so no critical information is missing. The openWorldHint is not elaborated, but it is not essential for a straightforward read 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?

The input schema fully documents the single parameter include_inactive with its meaning and default value (100% schema coverage). The description does not add extra parameter semantics beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the caller's active subscriptions.' It also enumerates the exact fields returned, making it clear what the tool does. This distinguishes it from sibling tools like subscribe/unsubscribe by focusing on read-only listing.

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 provides a usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to employ this tool versus alternatives like subscribe or unsubscribe.

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 alone (readOnlyHint=false, etc.) are minimal, but the description fully compensates by disclosing rate limits (5/day), free status, claim_token behavior, and that feedback is read daily and affects roadmap. It also instructs not to paste end-user prompts, adding context beyond annotations.

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

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

The description is long but every sentence carries useful guidance; there is no fluff. However, it is presented as a dense paragraph and could be better structured with bullets. The first sentence is front-loaded and clear, but the overall length is heavy for a simple feedback 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?

Despite having no output schema, the description thoroughly explains what a filing returns (claim_token), how to check status later, rate limits, and the key instructions for what to include or avoid. The nested context object is fully covered in both schema and description, making this complete for correct invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions, so baseline is 3. The description genuinely adds value by illustrating claim_token usage with format placeholder, providing message guidelines (be specific, don't paste prompt), and clarifying the context object's purpose, elevating it above schema alone.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team something is broken, missing, or needs to exist. It uses a specific verb ('Tell') and resource ('Pipeworx team'), and explicitly distinguishes it from sibling tools by limiting scope to tools served by this Pipeworx connection.

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: for bugs (wrong/stale data), feature/data gaps, and praise. It also gives a clear exclusion: do not use for tools from other MCP servers, and directs users to file with that server instead. Additionally, it explains follow-up usage via claim_token.

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 readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window'. This informs the agent about data provenance, privacy, and caching without contradicting the annotations.

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

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

The description is three sentences with no redundancy. It front-loads the core purpose, then use cases, then technical details. Every sentence adds distinct value, making it highly concise and well-structured.

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

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

The tool is simple (one optional param, no output schema), yet the description covers the return format ('top tools, top packs, and total call volume' and 'pack, tool, count'), behavioral traits, and use cases. This is complete for the tool's complexity.

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

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

The single parameter window is fully described in the schema, including semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description only adds that caching depends on the window, which is marginal beyond the schema. Baseline 3 is appropriate due to 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 clearly states what the tool does: 'What other AI agents are calling on Pipeworx right now' and explicitly lists the outputs ('top tools, top packs, and total call volume'). This specific verb+resource+output formulation distinguishes it from siblings like discover_tools and ask_pipeworx.

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

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

The description provides three explicit use cases, e.g., 'discovering what data sources are hot for current events' and 'confirming a popular tool is the canonical choice before asking your own question'. However, it does not name alternative tools or specify when not to use it, so it falls short of a 5.

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

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

The description discloses detailed behavioral traits beyond annotations: Jaccard similarity threshold for semantic matching, placeholder filtering logic, partition-sum tolerance, fill-check behavior against CLOB depth, and output structure. It complements the readOnly/idempotent annotations without contradicting them.

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

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

The description is dense and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), but it is notably long. While every sentence carries value, the length could hinder quick parsing; it is appropriately verbose 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?

With no output schema, the description carries full responsibility for explaining return values and behavior. It details opportunities[] and partition_check objects, edge cases (realizable_edge_pp ≤ 0), and cross-event limitations, making it fully self-contained for an agent selecting and invoking the tool.

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

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

The schema already covers both parameters, but the description enriches them with concrete examples, mode semantics, and the no-arg default behavior. It explains how `event` triggers partition checks and how `topic` enables cross-event scanning, adding significant meaning beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It provides specific verbs, resources, and methods, and clearly distinguishes from sibling tools like `polymarket_fill_risk` by focusing on arbitrage detection rather than sizing.

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

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

The description gives explicit invocation modes: no args for trending_scan, `event` for single-event, and `topic` for cross-event scanning. It recommends `event` for specific markets, explains when to use `topic`, and directs users to `polymarket_fill_risk` for custom sizing, providing clear decision boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond annotations: caching behavior ('Cached 1h at the KV level keyed on all knobs'), internal model logic (lognormal barrier, GDELT ratio, per-sport alpha), response structure with diagnostics, the 24h-move warning, and the tradeable-edge knobs. It explains why min_kelly never filters partitions and how placeholder slugs are handled. No contradictions.

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

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

The description is long but well-structured with labeled sections (segments, response top-level, knobs). It front-loads the core purpose and then details the segments and filters. Given the tool's complexity (9 params, 3 model families, diagnostics, caching), the length is justified. It is dense with information and doesn't contain redundant fluff, though a more telegraphic version could be imagined.

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: by_segment structure, fields like edge_pp_net, kelly_fraction, market.liquidity, and _diagnostics. It also covers model family calculations, exclusions, and edge-case behaviors (e.g., placeholders, partition Kelly). Given the complexity, this is a complete and self-sufficient description.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes far beyond the schema. It explains the semantic distinction between min_kelly and min_partition_leg_kelly, clarifies that edge is net of slippage, describes the effect of knobs like max_spread_pp and min_liquidity in practical terms, and labels them as 'TRADEABLE-EDGE KNOBS'. This adds meaning and prevents misuse, exceeding the baseline.

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

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

The description opens with a specific verb+resource+outcome: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreement and by detailing three distinct segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). This is far beyond a generic statement.

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

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

The description provides clear usage context: 'Built for "what should I bet on today"' and notes that Fed bets are excluded because the signal is unreliable. It does not explicitly name alternative tools for comparison, but it gives strong guidance on when to use this tool and how to apply knobs to filter opportunities. There is no explicit 'when not to use' mention, but the exclusions (e.g., Fed bets) serve as partial 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?

Despite annotations declaring readOnly/idempotent, the description goes far beyond them by detailing the 60-day snapshot TTL, cache-miss snapshot creation, gaps indicating no scan, and decay computed from daily closes net of slippage. This enriches the agent's understanding of edge cases and data provenance.

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

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

The description is long but densely packed with useful information, structured logically from purpose to args to response to limits. There is no filler, though the parenthetical metaphor ('the latter is wide for a reason...') could be trimmed without losing essential meaning.

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 explains the response structure: tracked[] with trend and decay fields, expired[] with lifespan, and snapshot_dates[] with gap semantics. It also covers limitations (TTL, daily closes), making the tool's behavior fully understandable without extra resources.

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 full descriptions for both parameters (days and window) with defaults and clamps. The description adds minimal new detail—'max 30' vs schema's 'clamp 2-30'—and otherwise repeats the schema information, so it stays at the baseline.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a specific verb ('track') and resource (edge persistence/decay) and distinguishes itself from siblings by focusing on historical behavior rather than current edges.

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

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

It provides a clear usage context via the example question 'how long has this edge existed and is it shrinking?' and explains why this matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly mention alternative tools or when not to use this one, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds substantial behavioral context: mode-specific execution (walks the ladder), output fields, verdicts, clamping, and the risk of partial basket fills converting arb into unhedged positions. No contradiction with annotations.

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

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

The description is long but well-structured with explicit SINGLE-MARKET and BASKET sections. Every sentence carries value, though some redundancy with the schema (e.g., side defaults, size_usd clamp) slightly reduces 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 (two modes, many outputs) and no output schema, the description compensates by listing all key return fields for both modes, including thin_legs, forced_directional_risk, and verdicts. It also covers risk notes and usage context, making it 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%, but the description adds meaning beyond it: explains side semantics in basket mode (sell_yes captures overround, buy_yes captures underround), clarifies size_usd as settlement notional in basket mode, and gives default logic. This helps the agent choose parameters correctly.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings by naming polymarket_arbitrage and polymarket_edges and stating 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?

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing thin-book overround and partial-fill directional risk, effectively excluding alternatives.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations: it details compatibility codes, temporal_mismatch vs temporal_alignment_unknown semantics, the fact that unknown legs are never paired, gross-vs-net fee limitations, and skipped-comparison counters. It also explicitly warns that both compatibility_warning and compatibility_codes[] can be non-empty even when pairs are returned, which is critical behavioral information.

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 the complexity of the tool justifies most of the length. It is well-organized with CAPITALIZED section labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loads the core purpose before caveats. Some redundancy exists — the per-entry flags repeat code definitions already enumerated globally — but the structure keeps it scannable.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it covers spread, top_spreads_pp, compatibility fields, temporal alignment, fee limitations, skipped counters, and unclassified-leg handling. Given three optional parameters and a complex safety surface, nothing essential for a correct first call 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 schema already describes all three parameters at 100% coverage, so baseline is 3. The description adds meaning beyond the schema by explaining the two-mode interaction, that explicit ticker/slug overrides the topic-mapped side, and that both modes run the identical token-overlap matcher with the same disclosures.

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: “Cross-venue spread between Kalshi and Polymarket for the same resolving question.” It clearly defines the two modes and differentiates itself from related polymarket siblings by emphasizing cross-venue comparison rather than single-venue pricing or 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 gives detailed mode-selection guidance (topic shortcuts vs explicit ticker/slug) and warns that pre-mapped topics often produce warnings rather than tradeable spreads. However, it never names alternatives like polymarket_arbitrage or bet_research or explains when to prefer them over this tool, so routing between sibling tools is left mostly 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?

With annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds valuable context that data is 'scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also explains the behavior of omitting the key to list all saved keys and the relationship to remember/forget. This goes beyond the annotations without any 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 three sentences, front-loaded with the core action, followed by usage context and scoping details. Every sentence adds distinct value: the first states what the tool does, the second explains when to use it, and the third provides scoping and sibling relationships. There is no redundancy or fluff.

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

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

For a simple tool with one optional parameter, the description covers all essential aspects: action, argument behavior, use cases, scoping, and related tools. It includes security/privacy context via identifier scoping, and the lack of an output schema is acceptable given the straightforward nature of 'retrieve value' or 'list keys.' The description is complete for the tool's complexity.

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

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

The input schema already covers the single parameter with 100% coverage ('Memory key to retrieve (omit to list all keys)'), so the baseline is 3. The description echoes the omit behavior and gives examples of saved values, but these are contextual illustrations rather than new parameter semantics. The parameter is simple and fully documented, so no additional explanation is needed.

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 action ('Retrieve a value previously saved via remember, or list all saved keys') and specifies the resource (saved memory values). It distinguishes itself from sibling tools by naming remember and forget as the counterpart actions, and provides concrete examples of use cases (user's target ticker, address, research notes). This is a specific verb+resource+scope formulation.

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

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

The description explicitly says 'Use to look up context the agent stored earlier... without re-deriving it from scratch,' which gives clear when-to-use guidance. It also instructs on the argument behavior ('omit the key argument' to list all keys) and points to alternatives via 'Pair with remember to save, forget to delete,' establishing a clear workflow and contrasting with sibling 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses behavioral side-effects: setting mark_read:true flags events read so subsequent calls only return newer items. It also mentions that polling is fine, implying no strict rate limits, and describes the return envelope (source, citation_uri, raw payload). This adds meaningful behavioral context that annotations alone do not 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?

Three sentences with every clause earning its place: main action, return fields, filtering, mark_read behavior, and polling/alternative endpoint. Front-loaded with the verb and resource. No redundancy or fluff, making 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?

For a read-only tool with 5 optional parameters and no output schema, the description is quite complete. It explains the return fields, the side-effect of mark_read, and provides an alternative data source. It doesn't mention error handling, pagination beyond the limit parameter, or what happens with no matching events, but these are minor gaps given the tool's simplicity.

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 references 'type' and 'since' filters and 'mark_read' but adds no new details beyond the schema. It does not clarify validation rules, format expectations, or interactions between parameters (e.g., whether limit and unread_only combine). Thus it adds minimal value over the structured 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 'Pull fired events from your subscription feed', which is a specific verb+resource statement that clearly distinguishes this tool from siblings like list_subscriptions (managing subscriptions) and recent_changes (watching changes). It also specifies the data source ('alerts the evaluator has written to your persisted feed') and key return fields (source, citation_uri, raw payload), making the tool's function unambiguous.

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

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

Provides clear usage context: filtering by type and since, marking events read, and unread_only mode. Explicitly mentions that polling works fine and offers an alternative HTTP endpoint for scripts/dashboards, which guides when to use the tool vs. direct retrieval. However, it doesn't explicitly compare to sibling tools in the same toolset or state when *not* to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the description doesn't need to restate safety. It adds substantial behavioral context: multi-source fan-out (SEC EDGAR, GDELT→GNews, USPTO), rate-limit fallback, soft-fail for patents, and the return structure. This goes well beyond annotations, giving the agent a clear model of what happens when the tool runs.

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?

Despite being long, every sentence contributes: user intents, core function, source details, fallback logic, parameter syntax, return shape, and alternative. It's a single dense paragraph that front-loads the most important information (what it does) before getting into specifics. No filler or redundancy.

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

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

The tool is complex (multi-source, fallback, flexible date parsing, citation URIs), and the description covers all these aspects without needing an output schema. It explains the return structure, source grouping, and limitations (patents soft-fail). It also positions the tool within the sibling set via the entity_profile contrast, making it fully contextualized.

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 extra value by clarifying `since` formats (ISO vs relative shorthand) with examples and a recommended usage ('Use "30d" or "1m" for typical monitoring'). This goes beyond the schema's basic description, though it doesn't add much for `type` and `value` since those are already well-described.

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

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

The description opens with concrete user intents ('What's new with X', 'latest on Y') and then clearly defines the tool: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It also explicitly contrasts with sibling tool entity_profile, which targets static profiles. This is a specific verb+resource+scope definition that distinguishes it from alternatives.

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

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

Provides explicit when-to-use triggers (queries about recent changes, news, updates) and a direct when-not-to-use recommendation: 'Use entity_profile instead when you want the static profile... regardless of window.' Also describes fallback behavior (GDELT→GNews, PatentsView sunset) which helps an agent decide if this tool fits the request.

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 idempotentHint=true and readOnlyHint=false, but the description adds valuable context: persistence terms (24 hours for anonymous, persistent for authenticated), scoping by identifier, and the key-value storage model. It doesn't explicitly state overwrite behavior, but idempotency covers that. There is 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 four sentences, each serving a clear purpose: purpose, when to use, storage semantics, and related tools. There is no fluff, and the structure is front-loaded with the primary action. It conveys substantial information efficiently.

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 storage tool with two well-documented parameters and no output schema, the description covers all relevant aspects: persistence, scoping, examples, and relationship to sibling tools. It is complete enough for an agent to use correctly without 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 schema provides 100% coverage for both parameters (key and value) with descriptive examples. The description adds limited extra semantics, such as the scoped by identifier and examples of valid keys/values, but this is marginal since the schema already explains the parameters. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the action (save) and the resource (key-value pair). It also distinguishes itself from related tools by explicitly mentioning 'Pair with recall to retrieve later, forget to delete,' which clarifies its role among 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?

The description gives explicit guidance on when to use: 'Use when you discover something worth carrying forward' with concrete examples. It also directs to alternatives (recall and forget) and explains the persistence behavior for authenticated versus anonymous sessions, leaving no ambiguity about 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?

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior, and the description adds substantial behavioral context beyond that: it explains that enrichment degrades gracefully, that unresolved identifiers are reported under 'unresolved' rather than omitted, that ambiguous name matches return 'figi_candidates', and that each call cascades through multiple internal endpoints. There is no contradiction between the description and 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 very long and dense, with nested parentheticals and run-on explanations inside the supported-types section. While most content is informative, it is not appropriately sized or front-loaded for quick comprehension; the core purpose is buried after several example phrasings and the giant company-type block is hard to parse. This is over-specification rather than 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 there is no output schema, the description carries the full burden of explaining what is returned and what can go wrong. It covers supported entity types, identifier sources, ambiguous-match behavior, unresolved-identifier reporting, enrichment degradation, and input constraints for both types. An agent has nearly everything needed to select and call 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?

Even though schema description coverage is 100%, the description adds meaning beyond the schema. It provides concrete examples for the 'value' parameter, distinguishes company inputs from drug inputs, explains ISIN resolution behavior, and gives an emphatic usage rule to pass the entity name only and never the full noun phrase. This materially helps an agent invoke the tool correctly.

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

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

The description opens with natural-language examples that make the tool's purpose immediately recognizable, then states a specific verb plus resource: resolve a user-spoken NAME to canonical/official identifiers. It also distinguishes itself from siblings by positioning the output as input for other tools, which is a clear differentiation from tools like entity_profile or compare_entities.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies which entity types are supported and how to ask for each. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds meaningful behavior: that it probes with ai_visibility_check, ranks by score, and returns a ranked list with score/confidence/signal density. It also explains that the first entity is treated as the subject, which is beyond the 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 three sentences, front-loaded with the core purpose, and includes a concrete example and return-value summary. Every sentence earns its place—no filler or redundancy.

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

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

With no output schema, the description appropriately summarizes the return format (ranked list with score, confidence, signal density). It explains the underlying mechanism (probe with ai_visibility_check) and mentions configurable models via the schema. Slight gaps remain around ranking methodology or potential errors, but these are not critical for selection.

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

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

Schema description coverage is 100%, and the schema already documents each parameter well, including the first-entity-as-subject rule. The description adds little beyond the schema, mostly rephrasing 'your brand + N competitors.' Since the schema carries the burden, the baseline of 3 applies.

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

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

The description opens with a specific verb phrase 'Compare AI visibility across multiple entities side-by-side' and immediately distinguishes itself from sibling tools by specifying it probes each entity with ai_visibility_check and ranks results. It clearly targets multi-entity competitive audits, differentiating from the single-entity ai_visibility_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?

It provides a concrete use case ('competitive AI-marketing audits') with an example query, and implicitly positions itself against ai_visibility_check by saying it probes each entity with that tool. However, it does not explicitly state when NOT to use it (e.g., for single entities) or name alternative tools like compare_entities.

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 readOnly, idempotent, and non-destructive. The description adds significant behavioral context: it is a composite call, may take 5-30s on first bundlephobia measurement, degrades gracefully with partial failures, and reports sources_failed. No contradiction with annotations.

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

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

The description is dense but well-structured: it front-loads the main purpose, then usage, then return format, ecosystem scope, and failure behavior. Every sentence adds necessary information for a composite tool, and no filler words are present.

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

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

With no output schema, the description must enumerate what is returned. It lists the summary block fields, per-advisory details, links, alternative versions, and sources_failed. It also notes the NPM-only scope and latency behavior, making it fully complete for decision-making.

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

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

The input schema has 100% coverage with clear descriptions for both 'package' and 'version'. The description mentions 'package' and 'latest version' implicitly but adds little parameter-specific meaning beyond the schema. It does not restate or contradict the schema, so the baseline 3 is appropriate.

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

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

The description clearly states a composite check for whether to add an npm package, specifying it fans out to deps.dev and bundlephobia and listing exact data points (license, advisories, bundle size). This specific verb-resource pairing distinguishes it from siblings like deep_research or validate_claim.

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

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

Explicitly says 'Use whenever an agent asks...' and provides concrete examples ('is X safe / popular / small'). Also gives an exclusion: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly', steering users 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 declare readOnly, openWorld, idempotent, and non-destructive hints, and the description adds significant behavioral detail beyond that: it discloses the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and the 200K character cap with truncation flagging. It also explains output traits like character offsets and similarity scores.

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

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

The description is front-loaded with the core purpose ('Search INSIDE a fetched record') and every subsequent sentence provides useful, non-redundant information: use case, benefits, pairing with an alternative, technical mechanism, and size limits. It is dense but not bloated, with no filler or repeating schema details.

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

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

Given there is no output schema, the description fully explains what the agent gets back: top-N passages with character offsets and similarity scores. It also covers the input cap (200K chars), truncation behavior, parameter defaults, and how to verify verbatim quotes, making it complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: it clarifies that `text` should be 'the text you already pulled' with real-world examples, and it gives concrete query examples like 'supply-chain risk' and 'fiscal year 2024 revenue.' This enriches the parameter meaning without being redundant.

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

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

The description uses a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes this from sibling tools by emphasizing it operates on already-fetched text (e.g., a SEC 10-K body) rather than performing broad retrieval, and it explicitly pairs with ask_pipeworx_grounded to clarify its niche.

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

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

The description provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also explains the benefit (saves context, returns only relevant passages) and contrasts with the alternative ask_pipeworx_grounded, telling the agent to fetch with the gateway and ground over relevant passages instead of the whole document.

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 a non-read-only, non-destructive, idempotent operation. The description adds meaningful behavioral context: OAuth account requirement for persistence, the always-on feed, delivery channel specifics (SMS verification, 10/day cap), and return of subscription id. 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 information-dense and front-loaded with the main purpose. Every sentence adds value, but it is a single long paragraph that could benefit from bullet points or section breaks for readability. Still appropriately sized 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?

The description covers prerequisites, return value, and delivery options, but lacks explicit mention of webhook (present in schema) and two supported types (patent_grant, clinical_trial). Without an output schema, it could better describe error cases or success indicators beyond the subscription ID. It is adequate but with clear 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?

With 100% schema description coverage, the schema already documents all parameters, but the description adds valuable concrete examples for sec_8k (e.g., items:['5.02'] = officer change) and delivery constraints. However, it omits webhook from the descriptive text and two supported types (patent_grant, clinical_trial), so it doesn't fully leverage the schema's additional detail.

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 action ('Create a proactive monitoring subscription') and identifies the resource ('live-data event stream') with a clear verb and result ('Returns the new subscription id'). It also distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 (to monitor live data), prerequisites (requires Pipeworx OAuth account), and consumption options ('feed always on — pull via recent_alerts'). It does not explicitly name alternatives but implies them through delivery channel details and mentions recent_alerts as a way to consume.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: it explains the tool returns category-bucketed example questions with exact tool+argument shapes from a live catalog, and that it can be focused by topic. This goes beyond the annotation baseline.

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 somewhat long but well-structured: it opens with user-intent phrases, explains the return format, then covers usage and parameter behavior. Every sentence contributes necessary onboarding information, though a few category examples could be trimmed.

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 communicates what the tool returns: category-bucketed example questions with the exact tool and argument shape. It covers invocation modes (no args vs topic) and the broader use case of learning meta-tools, making it self-sufficient for an agent.

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

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

Schema coverage is 100% with a good description for the topic parameter, but the tool description enriches semantics by explaining that omitting the parameter yields a full spread while providing it focuses the results. This adds value beyond the schema's 'Optional focus area' phrasing.

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

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

The description clearly states it is an onboarding entry point that returns example questions and maps them to tools, with a specific verb and resource. It distinguishes itself from sibling tools like discover_tools by positioning as 'Use this FIRST' and mentioning meta-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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the tradeoff between calling with no arguments versus passing a topic, providing clear context for when to use each mode.

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, the description discloses key behavioral traits: ownership enforcement, soft-delete (deactivated not deleted), and preservation of historical events via 'recent_alerts'. This adds valuable context beyond the annotation flags.

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

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

The description is two sentences, front-loaded with the action, and every sentence adds meaningful information. No wasted words.

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

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

For a single-parameter tool with no output schema, the description covers purpose, ownership constraints, side effects, and the relationship to 'recent_alerts'. It's fully self-contained and contextually complete.

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

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

Schema coverage is 100% and the 'id' parameter is well-described as a UUID returned by 'subscribe'. The description adds no additional parameter details, but since the schema is complete, the baseline 3 is appropriate.

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

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

The description states a specific action ('Cancel a subscription by id') with a clear resource (subscription) and identifier. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 clearly implies when to use it (to cancel a subscription you own) and adds ownership enforcement. It doesn't explicitly name alternatives but the context with siblings makes the use case obvious. Minor deduction for no explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds context beyond these: the verdict enumeration, the grounded/structured pipeline distinction, the meaning of could_not_verify (check did not happen) and unsupported (no source found), and the presence of verification_error with stage/detail. This helps the agent correctly handle not-yet-verified claims without falsely treating them as evidence.

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

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

Although the description is long, it is front-loaded with usage examples and flows logically: purpose, routing, return value, caveats, and added value. Every sentence contributes meaningful information—no filler or redundancy.

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

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

The tool has no output schema, so the description must explain return values. It specifies the possible verdicts, the actual value with citation, reasoning, and error semantics. It covers both company-financial and general factual claims. This is complete for an agent to invoke and interpret the result.

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

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

Schema coverage is 100% for both parameters. The description adds valuable nuances: it gives concrete examples for claim, and for tolerance_pct it explains that the default is implied by wording (capped at 5), and recommends 1–2 for hallucination detection. This enriches the schema's raw type/description with practical usage guidance.

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 claim-verification service with specific verbs like 'fact check' and 'verify the claim that…'. It distinguishes itself from siblings by describing the SEC EDGAR/XBRL fast path for company-financial claims and the grounded pipeline for other factual claims, and it explicitly states it replaces 4–6 sequential calls.

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

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

It explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples of natural-language triggers and describes the routing logic for different claim types. It also clarifies how to interpret edge-case verdicts like could_not_verify vs unsupported, which helps avoid misuse.

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