Warframe

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the default model is free, passing _apiKey enables Anthropic calls with direct payment, and it returns a per-model structure. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences with a clear flow: primary action, default/pricing caveat, return format, then use cases. No filler or redundancy; each sentence adds necessary information.

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

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

Without an output schema, the description compensates by including the return shape (per-model {score, confidence, signals, raw_response} + combined view). It also covers pricing, key usage, and typical applications. Minor gaps, such as what 'signals' means or how scores are computed, are understandable for a read-only tool with strong annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enhances parameter understanding by explaining default model behavior and how _apiKey is passed straight through to api.anthropic.com, including payment implications. This adds meaning beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This uses a specific verb (probe) and resource (LLMs), and the output (visibility score) differentiates it from sibling tools like entity_profile or ask_pipeworx.

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

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

The description provides clear use context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly mention when not to use it or name alternative tools, but the context is concrete enough for an agent to understand typical scenarios.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses behavioral traits such as routing across 5,564 tools, filling arguments automatically, returning structured answers with stable citation URIs, and working on every tier with 'one fast call'. This gives the agent a clear picture of what happens when invoking the tool.

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

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

The description is longer than typical but every sentence adds value: it starts with the key directive, provides concrete examples, and compares alternatives. It is well-structured and front-loaded, though it could be trimmed slightly without losing essential guidance.

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

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

Given the tool's broad scope, the description thoroughly covers input types (via examples), output format (structured answer with citations), use cases, and relationship to sibling tools. No output schema exists, so the description appropriately explains what the agent should expect in return.

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

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

The input schema already covers all parameters with 100% description coverage, listing question and aliases (q, text, input, query, prompt). The description text adds no additional parameter-level semantics beyond the schema, so it does not go beyond the baseline expected when schema coverage is high.

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 function: 'Routes the question to the right one of 5,564 tools across 1462 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes from siblings by naming ask_pipeworx_grounded and deep_research, making it clear this is the default general-purpose lookup tool.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and details when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also lists example queries and explicitly says to use it for factual questions even if web search could answer.

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

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

The description adds important behavioral context beyond annotations, including that candidate routing improvements may be enabled live during tests, that the last candidate was retired on 2026-07-26, and that this is a full working router rather than a fallback. It contradicts none of the existing readOnlyHint/openWorldHint/idempotentHint/destructiveHint 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 central fact that this is a beta version of ask_pipeworx, then adds relevant caveats about candidate routing and current behavior. It is slightly longer than strictly necessary due to the retirement backstory, but every sentence contributes to helping the agent understand when and why to use this experimental variant.

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 rich annotations and the open-ended nature of the tool, the description is fairly complete: it tells the request the routing architecture, the expected response shape (same as ask_pipeworx), and how the tool is currently configured. It does a bit less detail about the actual return format, but the openWorldHint and a question parameter indicate this is a natural-language answering tool.

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

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

The input schema has 100% description coverage and already documents the question parameter and all aliases (q, text, input, query, prompt). The description only says it shares the same arguments as ask_pipeworx, adding no new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description explicitly states it is a beta version of ask_pipeworx and an identical universal router with the same 5,564 tools, arguments, and response shape. This implies the purpose is to serve a natural-language question through the experimental routing edge. It distinguishes itself from siblings by noting it is the beta/experimental version, though it relies on the reader knowing ask_pipeworx for the full semantics.

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

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

The description gives an explicit usage directive: use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It also clarifies that no candidate is active right now, so the tool currently behaves identically to ask_pipeworx. It does not enumerate exclusion cases, but the beta-vs-stable 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds valuable context beyond these: it discloses refusal behavior with specific refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), defines the exact return structure {answer, evidence, confidence, source, fetched_at, refusal_reason}, and notes the extra LLM call cost. This goes beyond annotations without contradicting them.

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

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

The description is concise yet information-dense, with a logical flow: what it does, how it works, return format, when to use, and cost tradeoff. It front-loads the core purpose and includes only essential details. While slightly long, every sentence adds value without redundancy. Well-structured for agent consumption.

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

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

Given the tool's complexity – multiple routing steps, extraction, refusal logic, and exact return schema – the description is exceptionally complete. It explains the full behavioral contract, including success and refusal formats, cost implications, and use cases. The absence of an output schema is mitigated by explicitly enumerating the return fields and refusal reasons. No gaps remain.

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

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

Schema description coverage is 100% for the single required parameter, with aliases documented. The description itself doesn't add much parameter-specific meaning beyond what the schema already provides; it doesn't clarify format, length limits, or nuances of the question parameter. Since schema already covers it thoroughly, baseline 3 is appropriate – the description doesn't add extra value beyond the schema.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly identifying the tool's purpose as an answer-gathering mode with grounded extraction. It distinguishes itself from ask_pipeworx by explaining the same routing but with an added extraction step that uses only tool result content, and later contrasts with casual lookups. This is a specific verb+resource+mode with explicit differentiation from siblings.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). Also states when not to use: 'prefer ask_pipeworx for casual lookups' due to extra LLM call cost. This fully addresses when to choose this tool over alternatives.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by detailing resolver confidence levels (market_match_confidence), suppression of analysis on low-confidence matches, status codes like 'low_confidence_match' and 'market_closed_or_inactive', wide-spread liquidity warnings, and GDELT fallback behavior with retry_after_sec. It also explains cancellation-rule risk (refund_50_50, resolves_no_on_cancel, etc.) and how these affect EV. This is rich, actionable behavioral context that annotations don't provide.

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

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

The description is front-loaded with a clear purpose and organized into labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), which aids navigation. However, it is extremely long and includes extensive enumerations (classifiers, fan-out examples, cancellation-rule types) that could be partially moved to the schema or reference docs. While every sentence adds some value, the overall density makes it less concise than ideal.

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 the tool's behavior and returns. It thoroughly covers response shapes (result.market, result.analysis, result.evidence), resolver confidence, parent-event extraction, news fallback, blocking statuses, and resolution-rule risk. For a complex tool with 3 params and no output schema, this description is exceptionally complete and leaves few 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?

Even though schema coverage is 100%, the description adds significant meaning beyond the property definitions. For `market`, it clarifies that the tool resolves the market and fans out to classifiers, with concrete accepted forms (slug, URL, question text) and examples. For `include_raw`, it quantifies the response size trade-off (~20KB vs 50KB-500KB) and explains when to pass true. These details help agents make better parameter choices.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also states explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which clearly differentiates it from sibling tools like polymarket_edges or deep_research. The scope is unambiguous and tied to the tool's name and title.

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

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

The description gives clear context for when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also warns about blocking behavior on low-confidence or closed markets, which implies when it might not be useful. However, it does not explicitly name alternative tools or state when-not-to-use, so it stops short of a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and returning paired data with citation URIs. This goes well beyond the annotations.

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

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

The description is dense but well-structured: starts with usage examples, states the preference rule, then details per-type behavior and output. Every sentence adds valuable information, and the key guidance is front-loaded.

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

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

With only 2 params and no output schema, the description covers essential context: what the tool does, when to prefer it, data sources, output format (paired data + citation URIs), and sorting behavior. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with clear descriptions for 'type' and 'values', so baseline is 3. The description adds semantic richness by explaining what each entity type retrieves (e.g., 10-K financials for companies, FAERS counts for drugs) and providing examples for 'values', which helps the agent format appropriate inputs.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, using specific verbs like 'compare', 'rank', and 'head to head'. It distinguishes from sibling tools like entity_profile by emphasizing parallel vs sequential lookups and explicitly says it 'replaces 8–15 sequential lookups'.

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

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

The description provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives concrete example queries. It also outlines what each type ('company' vs 'drug') retrieves, helping the agent decide based on entity type.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds substantial beyond-annotation context: account/paywall requirements, latency expectations, never-invented evidence handling, explicit gaps[], contradiction scanning, semantically excerpted records, and fetchable citation URIs.

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

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

The description is dense and front-loaded with the most decision-critical info (account requirement, structured-data scope, not open-web search), and every clause carries useful operational detail. It is long but appropriately so for a complex tool; minor structural improvements like paragraph breaks would help.

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

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

With no output schema, the description fully compensates by specifying the findings packet structure: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop field. Latency and activation requirements are also covered, making this complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100% and the schema already describes both parameters well. The description adds meaningful semantic guidance on top: questions can be broad/multi-part, depth modes relate to facet count and follow-up hops, and 'thorough' requires a paid plan.

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

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

The description starts with a precise verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and explains decomposition and parallel routing. It clearly distinguishes from siblings by naming ask_pipeworx for single lookups and current news.

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

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

Explicit when-to-use and when-not-to-use guidance is present: use ask_pipeworx if not signed in, for single lookups, or for breaking/colloquial current news. It also explains depth tiers and second-hop behavior, so an agent can choose between this and 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 readOnlyHint=true and idempotentHint=true, and the description adds that it 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This discloses return content and that no second lookup is needed, going 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 packed with useful information but is somewhat run-on, combining a long domain list and return details into one sentence. Still, it is front-loaded with the core purpose and every clause adds context, so it earns a 4.

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?

As a meta-tool with no output schema, the description covers what it returns (names, descriptions, full schemas, examples) and when to invoke it. It also acknowledges the large sibling set by positioning itself as the first step for tool selection, making it complete for its role.

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

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

The input schema provides full descriptions for all six parameters, including aliases for query and the limit parameter. The description adds no additional parameter-level semantics beyond what the schema already states, 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 opens with 'Find tools by describing the data or task,' clearly stating the verb and resource. It also enumerates covered domains and explicitly frames it as a discovery tool, distinguishing it from the domain-specific sibling tools.

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

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

It states 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives explicit context and implies when not to use it (when you already know the tool).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds operational context beyond that: multi-source fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specific fallback behavior (GDELT→GNews); the USPTO PatentsView API sunset soft-fail; and return field details. This is valuable transparency without contradicting annotations.

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

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

The description is fairly long but packed with useful operational detail (sources, return fields, fallbacks). It starts with many example queries, which is helpful for intent matching but delays the core purpose. Each sentence serves a purpose, though it could be tightened and better structured (e.g., bullet points) for readability.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so thoroughly: lists cik + company_name, recent_filings with URIs, fundamentals sorted by period, patents, news via fallback, and LEI. It also mentions limitations (names not supported, patent API sunset). This is a complete enough picture for a complex multi-source tool.

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

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

Schema description coverage is 100%: both 'type' and 'value' have descriptions explaining allowed values and formats. The description adds examples (AAPL, 0000320193) and reiterates the resolve_entity fallback, but these are already present in the schema's value description, so no substantial new semantic meaning is added.

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

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

The description clearly states the tool produces a full cross-source profile of a US public company in one call, with specific examples and a clear resource (US public company). It differentiates from siblings by explicitly preferring it over chaining single-pack SEC/XBRL/news lookups for holistic views.

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: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also gives a when-not: "names not supported (use resolve_entity first if you only have a name)." This provides clear usage guidance and alternatives.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and pairing with remember/recall, but doesn't disclose additional behavioral details such as whether deletion is permanent or any side effects. It does not contradict 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 concise and front-loaded with the main action. Three short sentences cover purpose, usage, and related tools with no wasted words.

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

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

Given the tool's simplicity (one required parameter, no output schema, annotations covering destructive behavior), the description is fully adequate. It explains what the tool does, when to use it, and how it relates to siblings, leaving no critical gaps.

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

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

Schema coverage is 100%, with the only parameter 'key' described as 'Memory key to delete.' The description essentially repeats this ('Delete a previously stored memory by key') without adding extra meaning beyond what the schema already provides.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), and distinguishes from siblings like remember and recall by indicating it removes stored data.

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

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

The description gives explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references related tools ('Pair with remember and recall') but doesn't explicitly state when not to use the tool, so it falls short of full alternative exclusion.

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 explains the internal behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output format ('single text blob ready to drop at site-root/llms.txt'), adding value beyond the annotations that already declare read-only, idempotent, and non-destructive behavior.

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

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

The description is concise and well-structured. The first sentence packs the core function and target audience, the second explains the output, and the bulleted list provides concrete use cases without redundancy. Every sentence earns its place.

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

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

For a tool with only 2 parameters and no output schema, the description sufficiently covers the output format and the overall workflow. It explains what the tool produces and how it produces it, making it adequately complete for an agent to select and invoke it correctly.

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

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

The input schema already has 100% coverage for both parameters ('url' and 'max_links') with descriptive comments. The description does not add any additional parameter-specific semantics, so it relies on the schema, which is fully adequate.

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: 'Generate a production-ready llms.txt file for any URL' and explains the process it follows. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on generating the llms.txt file rather than merely checking AI visibility.

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 specific use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety. It adds useful behavioral context with 'Keyless, live' and explicitly lists the return fields, going beyond annotation data. 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 a single, front-loaded sentence that immediately states the tool's purpose and includes essential details without redundancy. Every word earns its place, and the structure is clear.

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

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

For a simple one-parameter list tool with no output schema, the description covers the main return fields and notes the keyless, live nature. It is sufficient for selection and invocation, though it lacks explicit mention of sorting, pagination, or error behavior, which may be unnecessary for this tool.

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

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

The schema fully documents the single platform parameter with a description and default (coverage 100%). The tool description adds no additional parameter-level meaning, but with full schema coverage, the baseline of 3 is appropriate.

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

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

The description explicitly states 'List the active Void Fissures' and enumerates specific details (Lith/Meso/Neo/Axi relic missions, Steel Path/Void Storm variants) and output fields (node, mission type, enemy, time remaining). This clearly distinguishes it from sibling tools like get_invasions or world_state.

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 use for retrieving current fissure missions and adds that it is 'Keyless, live', but it does not explicitly state when to use this tool vs alternatives or mention exclusions. No direct contrast with similar tools is provided.

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 as read-only, idempotent, and non-destructive. The description adds valuable context beyond those: 'Keyless' (no authentication required), 'live' (real-time data), and 'non-completed' (filtering behavior). It does not discuss rate limits or pagination, but with strong annotation coverage this is acceptable.

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 entire description is one concise sentence that front-loads the action and resource, then provides the key return details and behavioral notes. Zero filler.

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

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

For a simple list tool with one optional parameter and no output schema, the description is largely complete: it names the data returned, the live nature, and the filtering. It lacks explicit differentiation from siblings (get_fissures) but still gives sufficient context for selection and invocation.

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

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

The single optional parameter (platform) is fully documented in the schema with a clear description and default, so the description doesn't need to add more. The description's mention of 'keyless' pertains to authentication rather than parameter semantics; it does not enhance understanding of the platform field 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 ('List') and identifies the exact resource ('active faction Invasions'), and names the returned fields (node, factions, completion). It clearly distinguishes from sibling get_fissures by stating it's about Invasions specifically, not other world state.

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 usage for checking live, non-completed invasions and notes it's keyless, but it does not explicitly state when to use this over alternatives like get_fissures or world_state, nor does it provide any 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 indicate read-only, idempotent, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds value by specifying the returned fields and clarifying that only active subscriptions are listed by default (unless include_inactive is set). This contextual detail goes beyond the structured annotations, though it could have noted default filtering behavior more explicitly.

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 action and result. The first sentence states what it does and what it returns; the second explains practical usage. Every word earns its place, and there is no repetition of schema or annotation details.

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

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

With only one optional parameter, no output schema, and strong safety annotations, the description is complete. It lists the return fields, which compensates for the missing output schema, and gives clear usage context. Nothing critical is missing for a tool of this 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?

The input schema has 100% coverage: the only parameter, include_inactive, is fully described in the schema. The tool description does not add any extra semantic detail about the parameter. The baseline score for high schema coverage is 3, and the description neither improves nor worsens the parameter understanding.

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

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

The description begins with a clear, specific verb+resource: 'List the caller's active subscriptions.' It also enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count), making the tool's function unmistakable. The scope ('caller's') and the explicit mention of active subscriptions distinguish it from sibling tools like subscribe and unsubscribe.

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

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

The description provides concrete use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool relative to adding or canceling subscriptions. However, it does not explicitly name alternative tools (e.g., 'use subscribe to add more'), so it falls short of a 5, but the context is sufficiently 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 are all false, so description carries full burden. It discloses claim_token return, rate limit (5 per identifier per day), free/no-quota, daily digest reading, and roadmap impact. 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 every sentence earns its place: usage boundaries, token flow, rate limits, and cost are all necessary for a tool that could be misused. It is front-loaded with the core action, then adds critical operational 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?

Covers purpose, exclusions, input expectations, return/status behavior, rate limits, and cost. Given the nuanced claim-token mechanism and absence of an output schema, the description is fully self-sufficient. Sibling differentiation is clearly handled.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema, particularly for claim_token: explains that filing without an account returns it and that it can be passed back later to read the status. It also clarifies the context object's purpose in terms of Pipeworx tools/packs.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback types (bug, feature, data_gap, praise) and clearly distinguishes this from siblings like ask_pipeworx and research tools, which are for queries, not feedback.

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

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

Explicitly states when to use: for wrong/stale data (bug), missing catalog tools (feature/data_gap), or praise. Provides a clear exclusion: ONLY for Pipeworx-served tools, and directs users to file other-server issues elsewhere. Also advises not pasting user prompts and explains the claim_token flow for later checking.

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 indicate a safe read-only, idempotent, open-world operation. The description adds valuable context beyond that: it explains the data source (CF analytics-engine), states it contains no PII, describes the output shape (pack, tool, count), and discloses caching behavior (5min-1h). This enriches the behavioral understanding substantially.

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, then expands into use cases and behavioral specifics. It is slightly longer than strictly necessary, but every sentence contributes meaningful information and the structure is well-organized.

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

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

For a simple tool with one optional parameter, rich annotations, and no output schema, the description covers the return values, use cases, data source, privacy, and caching. This is fully sufficient for an agent to decide when and how to use 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 input schema provides 100% coverage with a detailed description of the 'window' parameter, including default behavior and the contrast between short and long windows. The tool description does not add further parameter semantics, 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 exactly what the tool does: it returns top tools, top packs, and total call volume over a recent window. This is a specific verb+resource+output and distinguishes it from sibling tools like discover_tools by focusing on aggregated agent call activity rather than general tool discovery.

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

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

The description provides clear use cases (discovering hot data sources, confirming canonical tool choice, aligning use cases with agent needs) which effectively indicate when to use this tool. However, it does not explicitly name alternatives 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?

Even though annotations already declare readOnlyHint and idempotentHint, the description adds deep behavioral context: it explains the partition_check threshold (deviations >3pp), the semantic anchor (Jaccard ≥0.30), the placeholder filter, and the fill check with realizable_edge_pp ≤ 0 meaning 'do not trade it'. No contradictions with annotations.

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

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

The description is long but tightly structured: first sentence states core purpose, then a quick mode overview, followed by mode-specific details, edge cases, and response format. Each sentence earns its place—there is no fluff or repetition, and key details like FILL CHECK and PARTITION FILTER are clearly labeled.

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 discloses return values: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge cases (placeholders, low similarity, book depth) and explicitly states the condition under which an arbitrage should not be traded, making the tool complete for agent use.

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

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

While the schema descriptions for event and topic are basic, the tool description vastly expands their meaning: it gives concrete slug examples (e.g., 'fed-decision-may-2026'), explains what each mode does internally, and even defines the no-arg trending_scan behavior. This goes well beyond the schema's 100% coverage.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_edges and polymarket_fill_risk by explaining the core techniques and then enumerating three distinct invocation modes.

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

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

Usage guidance is explicit and scenario-driven: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event for specific markets, topic for cross-event, and points to polymarket_fill_risk for custom sizing, effectively saying when to use this tool vs. an alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context beyond these: caching behavior ('Cached 1h at the KV level'), diagnostic output ('funnel counters, category_counts, filter_skips'), the 24h-move warning, slippage assumptions, and placeholder-slug filters. 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 and long, but every sentence conveys technical substance. It is front-loaded with the core purpose, then organized by segments and knobs. However, the lack of paragraph breaks and heavy use of ALL-CAPS makes it a wall of text, slightly reducing readability; otherwise it would earn 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 the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It fully enumerates the response structure (by_segment, fed_candidates/fed_note, _diagnostics), explains each model family's logic, and details how knobs affect filtering. Since there is no output schema, this description carries the full burden of explaining return values, and it meets that burden thoroughly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics by grouping knobs (e.g., 'Tradeable-edge filter' for min_liquidity/max_spread_pp) and explaining real-world rationale, such as 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade' for slippage_pp. This goes beyond what the schema provides, earning a 4.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings by detailing three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and their sub-models, making its scope unmistakable.

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

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

It explicitly states the intended use case ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and provides context on exclusions (Fed bets surfaced but excluded from ranking). However, it does not explicitly name alternative sibling tools (e.g., polymarket_arbitrage) 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 read-only/idempotent/non-destructive, and the description adds substantial behavioral detail: snapshots are written only on polymarket_edges cache-miss, gaps in snapshot_dates mean no scan occurred, history depth is bound by a 60-day TTL, and decay is computed from daily closes not intraday. This goes well beyond the structured annotations.

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

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

Despite its length, the description is information-dense and efficiently structured: purpose, arguments, response shape, and limitations are each covered in their own section. No sentence is wasted; it earns its length through non-obvious details like expired opportunities and the median-lifespan competition clock.

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, but the description compensates with a thorough breakdown of response fields (tracked, expired, snapshot_dates), their meaning, and caveats. It covers data freshness, lifespan, trend classification, decay measurement basis, and historical limits—making the tool's behavior understandable without additional docs.

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 both parameters have meaningful descriptions (days clamp 2-30 with default 14; window family among 24hr/1wk/1mo). The description restates defaults and adds 'snapshot family' context, but doesn't significantly extend parameter semantics beyond the schema.

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

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

The description opens with a specific verb phrase: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It explicitly frames the core question ('how long has this edge existed and is it shrinking?') and differentiates from siblings like polymarket_edges or polymarket_arbitrage by focusing on time-series persistence and decay rather than raw current edges or arbitrage opportunities.

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

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

The description gives clear use context: it answers 'how long has this edge existed and is it shrinking?' and explains why edge age matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name excluded alternatives or state 'use X instead of Y', so loses one point for lacking explicit when-not guidance.

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

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

The description adds significant behavioral context beyond the readOnlyHint: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about thin_legs and forced_directional_risk. It even discloses the dominant loss mode in arb-bot P&L. 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 tightly packed—every sentence adds functional or warning value. It uses mode-based organization (SINGLE-MARKET vs BASKET) and front-loads the purpose. However, the density could be slightly reduced without losing critical information, hence a 4.

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 takes on full responsibility for explaining return values. It enumerates all major fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers edge cases like partial fills and the need for a market or event parameter.

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 coverage is 100%, the description enriches each parameter with mode-specific semantics. For example, size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg; each share pays $1)' in basket mode. Side defaults are explained for both modes.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes and names sibling tools (polymarket_arbitrage, polymarket_edges), making its purpose unambiguous.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when not to rely on theoretical edge and identifies risks (partial basket fills convert arb into directional position).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true. The description adds substantial behavioral context: it explains when compatibility_warning fires, what temporal_alignment means, and how skipped_cross_type/subtype expose dropped comparisons. This goes far beyond the annotations and provides essential trust-related behavior 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 long and dense, but each sentence carries critical detail about modes, response fields, safety warnings, and temporal alignment. It is front-loaded with the core purpose, though it is written as a monolithic wall of text and could benefit from clearer structural formatting.

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

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

Even without an output schema, the description specifies the response structure (leg-by-leg prices, spread[], top_spreads_pp), safety fields with exact trigger conditions, and temporal alignment semantics. For a tool with this complexity, it gives the agent everything needed to interpret results and decide usability.

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 100% of parameters with descriptions, so baseline is 3. The description adds meaningful mode semantics: it explains that 'topic' auto-fetches matching events while explicit parameters override topic-mapped sides, and it lists the 10 pre-mapped shortcuts. This adds conceptual context beyond the schema's parameter-level 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly defining the tool's verb, resource, and scope. It distinguishes this tool from siblings by focusing specifically on cross-venue comparison between two named prediction markets.

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

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

The description provides two explicit modes (topic shortcuts vs explicit ticker/slug pairings) and warns that 'most pre-mapped topics return compatibility_warning today' and 'pre-mapped ≠ tradeable,' giving important when-to-use guidance. However, it does not explicitly name alternative sibling tools for different scenarios, so it lacks full exclusion 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 declare readOnly and idempotent, but the description adds non-obvious behavior: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and listing all keys when the key argument is omitted. It aligns with annotations and provides useful context beyond them.

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

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

Three purposeful sentences, front-loaded with the primary action, followed by usage context and related tools. 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 optional-parameter read tool, the description fully explains its purpose, scoping, modes, and relationship to siblings. With no output schema, the expected return context is clear from the description (value or list of keys).

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

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

Schema already covers the only parameter fully, including the omit-to-list-all behavior. The description repeats this in different words without adding new parameter-level semantics, so it meets the high-coverage baseline but not more.

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 ('Retrieve a value previously saved via remember') and a distinct resource (saved memory keys), with behavior clearly differentiated from sibling tools like remember and forget. It also conveys both modes: retrieve by key or list all keys when omitted.

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 when to use ('look up context the agent stored earlier... without re-deriving it from scratch') and names the companion tools ('Pair with remember to save, forget to delete'). This gives clear guidance on alternatives and workflow.

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 important behaviors beyond annotations: it returns raw event payloads with source and citation_uri, supports filtering by type and since, and the mark_read flag changes future outputs. It also states that polling is safe, which complements the readOnly/idempotent hints. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the primary purpose, and each sentence adds value: what it returns, how to filter, and the alternative access method. 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 tool with five optional parameters and no output schema, the description covers the return format, filtering, the mark_read side effect, and even provides an external endpoint for programmatic access. It is self-sufficient for understanding the tool's behavior, with schema covering parameter details.

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

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

While the schema already provides descriptions for all five parameters, the description adds meaningful context such as an example type ('sec_8k'), the consequence of mark_read (next call shows only newer events), and clarifies the semantics of 'since' as an ISO timestamp. This goes beyond the schema's standalone parameter descriptions.

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

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

The description opens with a clear, specific action: 'Pull fired events from your subscription feed.' It identifies the resource (subscription feed) and distinguishes the tool from siblings like list_subscriptions, which manages subscription settings rather than returning event data.

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

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

It gives practical usage context: polling is supported, and the same feed is available via HTTP for scripts/dashboards, implying the tool is optimized for interactive use. It also explains the effect of mark_read on future calls, guiding when to set it. However, it does not explicitly contrast with sibling tools like search_items or recent_changes, leaving some ambiguity about when to prefer this over alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds critical behavioral details: parallel fan-out to multiple sources, GDELT→GNews fallback for rate limits/5xx, USPTO soft-fail due to API sunset, and output structure with citation URIs. No contradictions.

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

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

The description is dense but every sentence earns its place: examples, source enumeration, fallback behavior, `since` syntax, output schema, and alternative tool. It is front-loaded with user intents and contains no filler.

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

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

Despite lacking an output schema, the description specifies return fields (changes[] grouped by source, total_changes count, pipeworx:// citation URIs) and covers failure modes and source behavior. This makes it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the description largely restates parameter examples (ticker/CIK for `value`, ISO/relative for `since`). It adds a typical use recommendation ('30d or 1m for typical monitoring') that goes slightly beyond the schema, but most semantic value still comes from the schema descriptions.

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

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

The description clearly defines the tool as a change feed for a company over a time window, with concrete query examples ('What's new with X', 'updates on Acme'). It lists the specific sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes from entity_profile, making the purpose unambiguous.

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

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

Provides explicit when-to-use guidance through query examples and an explicit alternative: 'Use entity_profile instead when you want the static profile...'. It also gives parameter usage advice ('Use 30d or 1m for typical monitoring'), ensuring the agent can select this tool appropriately.

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 write operation (readOnlyHint false) and idempotency (idempotentHint true). The description adds useful behavioral context beyond that: key-value storage scoped by identifier, retention details ('persistent memory' versus '24 hours' for anonymous), and the ability to pair with recall/forget. It does not explicitly state overwrite behavior on an existing key, but the idempotent hint partially covers that gap.

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 earning its place: purpose, usage, storage details, and companion tools. It is front-loaded with the main action and avoids wordiness while being comprehensive for the tool's simplicity.

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

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

For a simple two-parameter tool with no output schema, the description is complete: it covers what the tool does, when to use it, persistence semantics, and how to retrieve/delete. No significant gaps remain for an agent to decide correctly.

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

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

Schema coverage is 100% and each parameter already has a clear description ('key' with examples, 'value' with what to store). The tool description enriches this by giving real-world examples (resolved ticker, target address, user preference) and explaining the key-value pairing concept, adding value beyond 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 a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes the tool from siblings by explicitly pairing with 'recall to retrieve later, forget to delete,' and by mentioning cross-session persistence. This goes beyond a generic restatement of the name.

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 when you discover something worth carrying forward' and lists concrete examples like a resolved ticker or user preference. It also contrasts authenticated vs. anonymous sessions and names alternative tools (recall, forget), making the decision context 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 and idempotentHint, so the bar is lower. The description adds critical behavior: cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, how unresolved identifiers are explicitly stated, and that identifiers are source-labelled. 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 query examples and the key directive, then provides dense but relevant detail about company and drug resolution. While lengthy, every sentence adds value given the tool's complexity. Minor structural improvements (e.g., bullet points) could enhance readability, but it is already well-organized.

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

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

The tool has no output schema, so the description must explain return values and behavior. It does so comprehensively: listing output identifiers per type, mentioning source labels, explicit unresolved handling, and graceful degradation. For a moderately complex tool (2 entity types, multiple lookup sources), the description provides complete context for an agent to use it correctly.

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

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

Schema coverage is 100%, but the description goes far beyond. It explains how different inputs (ticker, CIK, ISIN, name) resolve for company, how ISIN-to-LEI mapping works for non-US issuers, the ownership resolution chain, and what outputs each type yields. For drug, it details RxCUI, ingredient, brand, and citation. All parameter nuances are thoroughly illuminated.

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, varied example queries that immediately clarify the tool's purpose. It explicitly states 'Use FIRST whenever you have a name but need an ID,' which sharply distinguishes it from sibling tools. It also details two specific entity types with clear resolution behavior.

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

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

The description provides explicit directives ('Use FIRST whenever you have a name but need an ID') and gives example scenarios. It explains that the tool replaces 2-3 manual lookups and describes graceful degradation. It does not explicitly contrast with direct siblings (e.g., entity_profile), but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnly/openWorld/idempotent and non-destructive, so the safety profile is covered. Description adds that it internally calls ai_visibility_check per entity, ranks by score, and returns ranked list with score, confidence, signal density. This goes beyond the annotation basics, though it doesn't mention call volume or rate limits.

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

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

Four sentences, front-loaded with the main action, and every sentence contributes either to the what, how, or when. No fluff.

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

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

For a tool with no output schema, it clearly states return values (ranked list with score, confidence, signal density), describes the internal workflow, and gives a typical use case. Combined with rich annotations and full parameter descriptions, nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics: the first entity is treated as the 'subject' and subsequent ones as competitors, and that each entity is probed via ai_visibility_check. This clarifies the entities parameter beyond its schema description.

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

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

Description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side'. It distinguishes from sibling ai_visibility_check (single-entity check) and compare_entities by specifying the AI-visibility focus, ranking, and competitor audit use case.

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: competitive AI-marketing audits and a concrete example question. However, it doesn't explicitly state when not to use it or mention alternative tools like compare_entities, though the context is fairly clear.

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

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

Beyond the annotations, the description discloses composite behavior (fans out across sources), partial failure degradation with graceful handling, and notable latency ('bundlephobia's first measurement on a new version can take 5-30s'). It explains that sources_failed will list timeouts while the rest still returns, adding value.

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 purpose and use cases, then covers return values, ecosystem scope, and failure behavior. No unnecessary words or repetition.

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

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

Given the tool's complexity (composite check, multiple sources) and the absence of an output schema, the description thoroughly explains the return summary block fields, per-advisory detail, links, alternative versions, and latency/failure behavior. It is complete for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions (package name, scoped packages, version defaults to latest). The description does not add significant additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool as a composite 'should I add this npm package to my project' check, fanning out to deps.dev and bundlephobia. It identifies the specific verb ('scan') and resource ('dependency'), and distinguishes itself from any sibling by describing its combined scope and NPM ecosystem focus.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states exclusions and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details beyond annotations: 'Fuzzy-search' indicates approximate matching, 'Keyless' indicates no authentication required, and it lists returned fields (name, type, category, description). These are useful nuances not present in the schema or 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, front-loaded sentence that conveys all essential information without filler. It earns every word, making it easily scannable for an AI agent.

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 search tool with one parameter and no output schema, the description is fully complete. It states the input (item name), the matching behavior (fuzzy), the access requirement (keyless), and the output fields, leaving no significant gaps.

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

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

Schema coverage is 100% with one parameter 'query', well described by the schema. The description adds the 'Fuzzy' and 'Keyless' context, which clarifies how the query parameter is interpreted and that no additional key is needed. This complements the schema 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 clearly states a specific verb ('Fuzzy-search'), a resource ('Warframe item data'), and scope ('by name'). It also enumerates item categories and distinguishes itself from sibling tools by focusing on Warframe items, which no other sibling does.

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

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

The description provides clear context on what the tool does ('Fuzzy-search Warframe items by name', 'Keyless') and what it returns, which implies when to use it. It does not explicitly exclude alternatives, but none of the sibling tools offer similar functionality, so no conflict exists.

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 as read-only, idempotent, non-destructive. The description goes beyond by revealing implementation details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and character offsets for verification. This adds meaningful behavioral context not present in annotations.

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

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

The description is front-loaded with the core purpose, then expands with examples, usage guidance, and technical details. Every sentence earns its place, and the flow from what/why/how is logical. No filler or repetition.

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

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

Without an output schema, the description explains the return format (top-N passages, offsets, similarity scores). It covers input examples, limits, truncation behavior, and a sibling tool for grounding. For a tool with this complexity, it is fully self-contained and addresses both functional and edge-case aspects.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving examples for query ('supply-chain risk'), clarifying text type ('long tool result'), and explicitly stating the truncation flag for text over 200K chars. These details enhance understanding beyond schema descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with a specific verb and resource. It distinguishes itself from siblings by name-dropping ask_pipeworx_grounded and describing the workflow (fetch then search within). Examples like 'SEC 10-K body' make the purpose concrete.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. It also provides an alternative workflow with ask_pipeworx_grounded, telling the agent to ground over passages rather than the whole document. This is clear, actionable guidance.

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

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

The description adds substantial behavioral context beyond annotations: OAuth requirement, delivery channel options (feed, email, SMS) with specific constraints (SMS phone verification, 10/day cap), and the return of a subscription id. These are not inferable from the readOnly/idempotent/destructive hints. It doesn't contradict any annotation, and while it doesn't mention webhook (covered in schema), it provides rich operational detail.

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

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

The description is dense but logically structured: purpose, return value, requirement, types, and delivery options. Every sentence adds value, though it is longer than strictly necessary. The front-loading of the core action and id keeps it scannable. Slight length prevents a 5.

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

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

Given the tool's complexity (nested params, multiple enum options, no output schema), the description covers the key points: what it returns, prerequisites, supported types, and delivery channels. It doesn't mention error cases or webhook behavior, but those are partially covered in the schema. It is adequate for an agent to select and invoke the tool correctly.

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

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

Even though schema coverage is 100%, the description adds interpretive meaning for each type, such as 'items:["5.02"] = officer change' for sec_8k and 'cross-venue mispricings' for polymarket_edge. It also clarifies delivery channel semantics. This goes beyond the schema's parameter descriptions, which are more structural.

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 specific action: 'Create a proactive monitoring subscription to a live-data event stream' and notes it returns the subscription id. This distinguishes it from sibling tools like list_subscriptions and unsubscribe. It also details the supported subscription types, making the purpose unmistakable.

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

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

The description provides clear context on when to use the tool (to set up proactive monitoring) and prerequisites (requires OAuth account). It also mentions the always-on feed and how to pull alerts via recent_alerts, implicitly distinguishing from reactive retrieval. However, it does not explicitly name alternatives like list_subscriptions or unsubscribe, so it falls slightly short of the highest bar.

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

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

While annotations already declare readOnly/openWorld/idempotent, the description adds meaningful behavioral context: output format (category-bucketed examples with tool+argument shape), data source (live catalog of thousands of tools), and dynamic scope behavior (full spread vs. focused topic). It does not contradict annotations and enriches understanding of what the return value contains.

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 not overly long. The opening example queries serve as concrete search triggers, and the explanation is structured clearly across sentences. Each sentence contributes to purpose, usage, or output detail. A minor length reduction could improve conciseness without losing value.

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

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

Given only one optional parameter and no output schema, the description fully compensates by explaining return structure (category-bucketed examples), how to focus, and its role as an onboarding gateway to meta-tools. It also covers the live-catalog nature, making it complete for an agent deciding whether to invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by clarifying that omitting `topic` yields a cross-category spread and gives concrete examples (finance, pharma, betting) that map to schema enums. This adds practical meaning to the parameter's behavior.

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 returns category-bucketed example questions with exact tool/argument shapes, positioning it as the onboarding entry point. It distinguishes itself from siblings by explicitly naming it the FIRST tool to use when unfamiliar with Pipeworx, contrasting with meta-tools and other discovery mechanisms.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains how to call it (with or without `topic`) and that omitting returns a cross-category spread. This meets the 'explicit when/alternatives' criterion by positioning it as the starting point relative to other tools.

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

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

The description discloses that the row is 'deactivated (not deleted)' and that historical events remain accessible via recent_alerts, which enriches the annotations. It also mentions ownership enforcement, providing behavioral context beyond the structured metadata.

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

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

Two sentences, front-loaded with the primary action, and every sentence adds meaningful information without redundancy. It is compact and easily parseable.

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

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

For a simple one-parameter idempotent operation, the description covers the action, ownership, side-effect behavior, and data retention. It fully equips an agent to understand what happens when invoking the tool, despite having no output schema.

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

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

The schema already documents the id parameter fully (type, description, and source from subscribe). The description's mention of 'by id' and 'returned by subscribe' reinforces but does not add new semantic value beyond the schema coverage.

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

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

The description opens with 'Cancel a subscription by id,' a specific verb+resource statement that clearly defines the tool's action. It distinguishes itself from siblings like subscribe and list_subscriptions by directly stating the cancellation function.

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

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

It implies when to use the tool (to cancel a subscription) and adds an ownership restriction ('you can only cancel your own subscriptions'). However, it does not explicitly mention alternative approaches or exclusions, though none exist among siblings for cancellation.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds rich behavioral context: the dual structured/grounded pipeline, the enumeration of verdict values, and crucially the distinction between could_not_verify (check did not happen) and unsupported (no source covers it), plus the warning not to treat could_not_verify as evidence. This is exactly the kind of edge-case transparency that prevents agent misuse.

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

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

The description is long but highly information-dense and logically ordered: trigger phrases, purpose, routing, return contract, error semantics, and a performance claim. It front-loads the trigger examples and ends with a time-saving note. While not terse, every sentence carries meaningful content and the structure aids parsing.

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

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

For a tool with no output schema, the description fully specifies the return contract (verdict strings, actual value with citation, reasoning) and explains all non-obvious verdict values. It also describes the underlying data sources (SEC EDGAR + XBRL, grounded pipeline) and covers failure modes. Given the tool's complexity, this is arguably complete without needing an output schema.

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

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

Schema coverage is 100% with both parameters documented. The description goes further by explaining tolerance_pct's override semantics, its default behavior ('implied by wording, capped at 5'), and a concrete use case ('set 1–2 for hallucination detection'). This adds real guidance beyond the schema's basic field description.

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

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

The description opens with concrete trigger phrases ('Is it true that…' / 'fact check') and states a sharp purpose: natural-language claim verification against authoritative sources. It clearly distinguishes from siblings by positioning itself as the direct fact-checking tool and 'Replaces 4–6 sequential calls', which differentiates it from multi-step research tools like deep_research or 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?

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for company-financial vs. other claims. It lacks an explicit 'when not to use' or named alternative tools, but the use case is unambiguous enough for an agent to select it appropriately.

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, open-world, and non-destructive hints. The description adds valuable context by noting it is 'Keyless, live' and by listing the exact data points returned, enriching understanding beyond the annotations without contradicting them.

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

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

The description is two sentences long, front-loaded with 'One-call summary,' and every word serves a purpose. It lists the included elements compactly without verbosity, making it an excellent example of concise writing.

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

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

The tool is simple (one optional parameter, no output schema) and the description clearly lists the data it provides. It doesn't explicitly describe the return format or any caveats, but for a summary tool, the information given is sufficient for an agent to decide when to call it. Slightly more detail on response structure would make 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?

The schema description covers 100% of the platform parameter, specifying allowed values and default. The tool description adds no further semantic meaning about the parameter, so a baseline score of 3 is appropriate.

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

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

The description clearly states it is a 'One-call summary' of Warframe's live worldstate and enumerates the specific components (Cetus cycle, Cambion Drift, Orb Vallis, Sortie, Baro, Void Fissure count). This distinguishes it from sibling tools like get_fissures and get_invasions that focus on narrower data.

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

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

The phrase 'One-call summary' clearly implies using this tool to get a broad overview of worldstate data in a single request, which helps select it over more specialized tools. However, it does not explicitly name alternatives or state when not to use it, so it doesn't earn a 5.

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