superhero

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

Annotations already establish read-only, open-world, idempotent behavior. The description adds valuable behavioral context beyond these: it reveals the default model, the cost/auth implication of using Anthropic ('you pay Anthropic directly'), and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This exceeds the baseline expected given annotations and fully discloses relevant side effects (no side effects, but cost is disclosed).

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

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

The description is three sentences, front-loaded with the core purpose. It packs essential details (default model, cost, return format, use cases) without redundancy. Every sentence contributes meaningful information, and the structure flows logically from what → how → when.

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

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

The description is complete for a read-only analysis tool: it explains inputs, outputs (including per-model response structure), default behavior, optional key handling, and typical use cases. With no output schema present, the description adequately covers return values. Given the tool's moderate complexity (4 params, 1 required), this is sufficient for correct invocation.

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

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

Schema coverage is 100%, so each parameter already has a description. However, the description adds meaning by clarifying the default model ('Default model is Workers AI Llama-3.3-70b'), the conditional nature of `_apiKey` ('only needed if anthropic is in models'), and that the key is 'passed straight through' to Anthropic. These details go beyond the schema and help the agent understand parameter interdependencies.

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 ('Probe') and resource ('LLMs'), and clearly states the output ('score visibility (0-100) per model'). This unambiguously differentiates it from sibling tools like scan_competitor_ai_presence by focusing on per-model scoring across multiple LLMs rather than presence in a single source.

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-case context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs. optional model (Workers AI free, Anthropic BYO key). It does not explicitly mention when not to use the tool or name alternative tools, but the described scenarios are sufficient 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about routing, argument filling, stable citation URIs, and per-tier availability. It does not contradict annotations, and while it doesn't discuss failure modes, the safety profile is already covered.

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 relatively long but every section serves a purpose: the strong directive, domain list, example phrasings, and escalation path. It is front-loaded with the key 'prefer over web search' message. Minor redundancy ('even if web search could also answer it') but overall efficient.

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 clarifies the return format (structured answer with citation URIs). It covers scope, default usage, alternatives, and exceptions (e.g., breaking news) comprehensively. The complexity of the tool is high, but the description fully equips an agent to decide when 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% with the 'question' parameter and all aliases documented. The description reinforces semantics by stating the tool answers natural language factual queries and provides concrete examples ('what is', 'look up', 'find'). This adds context beyond the schema's simple 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 explicitly states the tool routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citations. This is a specific verb+resource pairing, clearly distinguishing it from web search and sibling tools like deep_research.

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 opens with 'PREFER OVER WEB SEARCH' and provides explicit when-to-use directives for many domains. It also names alternatives: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad questions, and notes how it handles breaking news. This is explicit when/when-not/alternatives.

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

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

Annotations already provide read-only, idempotent, and open-world hints. The description adds crucial context beyond that: it's an experimental live edge, candidates may be enabled while under test, current state has no active candidate, and it does not fall back—it's a fully working router. This discloses behavior not derivable from annotations.

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

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

Four sentences, each earning its place by conveying beta status, current state, usage guidance, and fallback assurance. Slightly longer than minimal but well-structured and front-loaded with the most important distinguishing information. Not excessive enough for a 3.

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 (a universal router with 5,529 tools), the description covers everything needed: what it is, current operational state, how to use it, and that response shape matches ask_pipeworx. No output schema exists, but referencing the sibling's response shape suffices. Complete and self-contained.

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

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

Schema description coverage is 100%—all six parameters are clearly documented as aliases for 'question'. The description adds no new parameter semantics, only mentioning 'same arguments' which is redundant with the schema. Baseline 3 is appropriate since the schema fully covers parameter meaning.

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

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

The description clearly identifies this as a beta version of ask_pipeworx with the same 5,529 tools and response shape. It explicitly differentiates from the stable sibling by noting it experiments with candidate routing improvements. The verb 'ask' and resource 'pipeworx' are specific and unambiguous.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also implies the alternative of using the stable ask_pipeworx for non-experimental needs, and explains that results are compared against the stable router. Clear context for tool selection.

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

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

Despite strong annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral detail: the two-step routing/extraction process, exact success and refusal return shapes, specific refusal reasons, and the extra LLM call cost. It also clarifies that extraction uses ONLY tool result content, reinforcing the read-only and grounded 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 dense but every sentence contributes: purpose, mechanism, return contract, refusal cases, use cases, and cost trade-off. It is front-loaded with the core value proposition and avoids fluff or repetition of schema 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 complex tool with no output schema, the description fully compensates by specifying success/error response shapes, refusal reasons, and usage boundaries. It also provides enough context to choose between this and the sibling ask_pipeworx tool.

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

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

Schema coverage is 100%, with the 'question' field and all aliases clearly documented in the schema. The description adds no additional parameter-level detail, but the baseline of 3 applies because the schema already carries the semantic weight.

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

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

The description clearly identifies this as a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb (ask/extract) and resource (Pipeworx tool routing). It explicitly distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and refusing when data doesn't directly answer.

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 lists example domains. It also gives a direct alternative and trade-off: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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 provides extensive behavioral context beyond the read-only/idempotent annotations: fan-out strategies per classifier, the resolver contract with confidence levels, parent-event extraction, fallback handling for GDELT 429s, status codes like 'low_confidence_match' and 'market_closed_or_inactive', wide-spread market markers, and cancellation-rule risk with void-settlement implications. This is a rich disclosure of what happens inside 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 dense and information-rich, but it is presented as one continuous block without sections or formatting, making it hard to scan. While every sentence adds value, the lack of visual structure and the sheer length prevent it from being concise. It is adequate but not exemplary.

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 what the tool returns. It thoroughly covers response shapes for market, analysis, and evidence, plus resolver contract fields, parent_event, news fallback fields, security short-circuiting, and resolution-rule risk. No important aspect seems missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by giving concrete examples for the 'market' parameter (slug, URL, question text) and by explaining fan-out behavior tied to classifiers. It also clarifies the effect of 'depth' ('quick = 2-3 evidence sources, thorough = full fan-out') and 'include_raw', adding practical meaning beyond the schema.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' This clearly states the tool's function and differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on arbitrage or edge detection rather than comprehensive research.

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 lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This is clear 'when to use' guidance. However, it does not explicitly mention when not to use or name alternative tools, so it falls short of a 5 on the rubric.

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

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

Beyond the annotations (read-only, idempotent, open world), the description discloses substantive behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, return of paired data with citation URIs, and a single parallel call that replaces 8–15 lookups. This greatly exceeds the minimal safety profile provided by annotations.

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

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

The description is dense but every sentence earns its place—trigger phrases, data sources, sorting behavior, and efficiency benefit. It is front-loaded with the most important usage instructions ('ALWAYS PREFER'), making it easy to scan. 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?

Given no output schema, the description thoroughly covers return values (paired data + citation URIs), sorting behavior, and the parallel-call efficiency. It also handles both entity types and their data specifics, making it sufficiently complete for an agent to know what to expect and how to invoke the tool.

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

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

Schema coverage is 100%, but the description adds significant semantic detail: it explains exactly what data each 'type' retrieves (10-K financials for companies, adverse-event/trial counts for drugs) and clarifies the values parameter examples. This goes well beyond the schema's basic field descriptions, enriching the agent's understanding of expected inputs and outputs.

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. It includes specific trigger phrases and distinguishes itself from sequential single-entity lookups, making its purpose unambiguous and differentiating it from sibling tools like entity_profile.

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

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

The description explicitly says to 'ALWAYS PREFER' this tool over sequential single-pack lookups when comparing entities, providing clear when-to-use context. It also gives query examples and type-specific data sources, but it does not name alternative tools explicitly or discuss when not to use it beyond the sequential vs. parallel distinction.

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 reveals extensive behavioral traits beyond the annotations: account/plan requirements, decomposition into facets, parallel routing, the return packet with citations, explicit gaps[] that are never invented, contradictions[] for deeper depths, semantic excerpting, resolvable citation_uri rules, and latency ranges. The annotations only cover readonly/openworld/idempotency, so this substantial added context is vital.

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 justifiably dense; every sentence carries operational significance — from account prerequisites to return packet structure, gaps, citations, excerpting, and latency. It is front-loaded with the most critical constraints (account required, alternative tool). There is no redundancy or filler; every clause earns its place.

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

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

With no output schema, the description fully explains the return value: findings packet with verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[], and hop field. It also covers latency and edge cases like unresolved facets and citation resolvability. For a complex research tool, this is exceptional completeness.

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

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

Although the schema covers both parameters (question and depth) with descriptions, the tool description enriches them substantially: it explains what 'quick', 'standard', and 'thorough' actually do (number of facets, hop behavior, contradiction scanning), and clarifies that 'question' can be broad/multi-part because decomposition is the point. This goes well beyond the schema's enum values.

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+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It explicitly distinguishes from open-web search and names sibling alternatives like ask_pipeworx, making the tool's scope and differentiation 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?

Provides explicit usage criteria: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx', plus 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes account requirements and the fallback to ask_pipeworx when not signed in. This gives clear when-to-use vs. when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe-read nature is covered. The description adds beyond that by revealing the output structure: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This tells the agent what to expect from the call without needing an output schema.

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

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

The description is front-loaded with the core purpose, followed by a relevant domain list, then the return format and usage timing. Each sentence adds distinct information without redundancy, and the length is justified given the tool's broad scope.

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

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

The description covers what the tool does, when to call it, and what it returns (top-N tools with schemas and examples). Despite no output schema, the return format is explicitly stated, making the tool fully self-contained for an agent to call and use the result.

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

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

Schema coverage is 100% and describes query plus all aliases (q, task, search, description) and limit. The description mainly repeats this by saying 'Find tools by describing the data or task' and noting natural language input. No additional semantic value beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It then enumerates a broad but concrete set of domains (SEC filings, FDA drugs, FRED, etc.), making it clear this is a discovery/meta-tool distinct from siblings that perform domain-specific queries.

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 ('Use when you need to browse, search, look up, or discover what tools exist for...') and provides a direct directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This differentiates it from answer-focused tools and gives actionable timing 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 rich detail beyond the readOnlyHint annotation: it reveals the fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; discloses the patents soft-fail due to API sunset; and describes the return structure with specific fields. This gives the agent confidence in what will happen and what to expect.

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

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

The description is fairly long but every sentence contributes meaningful information: usage examples, scope, data sources, return fields, and an explicit limitation. It is front-loaded with a clear purpose. It loses one point for density—could be tightened with bullet points—but remains appropriately informative.

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

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

With no output schema, the description fully compensates by enumerating all return components (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and notes the fallback behavior. For a multi-source aggregation tool, this is complete enough for an agent to invoke it correctly and interpret results.

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

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

The schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds value by reinforcing the accepted formats (ticker or zero-padded CIK) with concrete examples and clarifying the exclusion of names, which goes beyond just repeating the schema. This earns 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 clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It provides specific example queries and lists the exact data sources and outputs, making it unmistakably distinct from siblings like resolve_entity or single-source lookup tools.

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

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

Explicitly states when to use it: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explains when NOT to use it (names not supported) and points to an alternative: 'use resolve_entity first if you only have a name.' This is comprehensive guidance.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description doesn't need to repeat those. It adds minimal behavioral context beyond stating the delete action and mentioning 'sensitive data,' but does not disclose additional traits like permissions or edge cases. The bar is lower with annotations, yet the added value is limited.

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

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

Two sentences, front-loaded with the core action. The first sentence is immediately informative, and the second adds usage context without verbosity. Every word 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 simple tool with one parameter, existing annotations, and no output schema, the description covers the essential purpose, usage, and relationship to siblings. It is sufficient 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?

The input schema fully describes the single 'key' parameter with 100% coverage. The description only repeats 'by key' without adding format, constraints, or examples beyond what the schema already provides, so it meets the baseline but adds no extra value.

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

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

The description clearly states the tool's action with a specific verb and resource: 'Delete a previously stored memory by key.' It distinguishes itself from sibling tools like remember and recall by focusing on deletion of existing memories.

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

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

Explicitly provides when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also references alternatives by pairing with remember and recall, giving the agent clear guidance on inter-tool relationships.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'. It also clarifies the output as 'a single text blob ready to drop at site-root/llms.txt'. This gives the agent a clear model of the tool's behavior without contradicting annotations.

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

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

The description is three sentences, with the core purpose and process in the first sentence, output format in the second, and use cases in the third. Every sentence adds meaningful information with no redundancy. It is front-loaded and well-structured.

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

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

For a relatively simple tool with no output schema, the description covers the essential aspects: what it does, how it works (fetch, extract, emit), the output format, and practical applications. Combined with complete schema annotations and parameter descriptions, the context is fully adequate.

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

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

The input schema already provides 100% coverage for both parameters (url and max_links) with descriptive text. The description adds no additional parameter-specific meaning beyond what the schema gives, meeting the baseline of 3. It does not enhance or clarify parameter usage further.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It specifies the verb (generate), resource (llms.txt file), and differentiates from siblings by mentioning the exact output and use cases like AI crawler indexing and competitor auditing. This is a specific, non-tautological description.

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

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

The description provides explicit use cases: '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'. This gives clear context for when to use the tool, but it does not mention exclusions or alternative tools like 'ai_visibility_check' or 'scan_competitor_ai_presence'. Therefore, it falls short of a 5 but exceeds a 3.

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 no new behavioral disclosures beyond listing output fields, and it is consistent with the annotations.

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

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

One concise sentence, no redundant words, and the field list efficiently specifies the scope without wasted prose.

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

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

For a simple read-only lookup with one parameter, rich annotations, and an existing output schema, the description is fully adequate and leaves no critical gaps for correct invocation.

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

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

Schema coverage is 100% with a clear description for the single parameter 'id' (Numeric superhero ID 1–731). The description only says 'by ID', adding no additional semantic detail, so baseline 3 applies.

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

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

The description uses the specific verb 'Get' and identifies the resource as 'biography details' with a precise field list (full name, aliases, publisher, first appearance, alignment), clearly distinguishing it from siblings like get_hero or get_powerstats.

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?

No explicit when-to-use or alternative guidance is provided. The phrase 'by ID' implies the need for a numeric superhero ID, but it does not explain when to choose this over get_hero or get_powerstats, though the listed fields hint at biography-specific uses.

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 behavior. The description adds value by specifying the return content, which is useful context. No additional behavioral traits are disclosed, but with annotations covering safety, this is sufficient.

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?

A single sentence, front-loaded with the verb and resource, and zero wasted words. It clearly communicates purpose and scope.

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

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

For a simple single-parameter tool with a rich output schema and strong annotations, the description is complete enough. It states what is returned and the key input requirement, and the output schema covers return 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?

Schema coverage is 100% and the parameter description already provides the ID range (1–731). The description only repeats 'numeric ID' without adding new semantics, so baseline 3 is appropriate.

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

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

Description clearly states the tool returns full superhero data by numeric ID, listing content categories (powerstats, biography, appearance, images). This distinguishes it from siblings like get_biography and get_powerstats.

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 when complete hero data is needed, but does not explicitly mention alternatives or exclusions. Sibling tools exist, so the context is clear enough for an agent to infer when to use this over more specific tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, and the description adds a list of included stats but no further behavioral context like error cases or return format beyond what the output schema likely covers.

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?

A single, front-loaded sentence that contains all necessary information without any filler or redundant phrasing.

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

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

For a simple read-only lookup with one well-documented parameter and a likely output schema, the description is fully sufficient and leaves no critical gaps for an agent to misuse 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% and the single id parameter is well-described with a range (1–731); the description adds no further semantic value to the parameter beyond what the schema provides.

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

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

The description uses a specific verb ('Get') and resource ('power statistics') and clearly qualifies by ID, distinguishing it from sibling tools like get_hero and get_biography.

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 makes clear it is for retrieving power statistics for a hero by ID, which implicitly suggests when to use it, though it does not explicitly mention alternatives when full hero data or biography is needed.

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

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

Annotations already declare the tool read-only, open-world, idempotent, and non-destructive, covering the safety profile. The description adds that it returns all superheroes and specific fields, but does not disclose behavioral traits like pagination, sorting, or potential data volume. 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 succinctly states the action, scope, and returned fields without any redundancy or filler words.

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

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

For a tool with no parameters, strong safety annotations, and an existing output schema, the description fully captures the tool's purpose and expected return content. Nothing critical is missing for an agent to invoke it correctly.

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

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

The input schema has zero parameters, so there is no parameter detail to add. Per the rubric, 0 params earns a baseline of 4; the description is not required to compensate for missing schema information.

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

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

The description uses the specific verb 'List' and clearly states the resource ('all superheroes in the database') and the returned fields (IDs, names, slugs). The scope of 'all' distinguishes it from siblings like get_hero, which retrieves a single hero.

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 the tool is used for retrieving a complete list of superheroes, but it does not explicitly state when to use it over alternatives such as get_hero or search_within, nor does it mention any exclusions or prerequisites.

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

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

Annotations already declare read-only and safe behavior, and the description adds value by disclosing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the default filtering to active subscriptions. 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 two sentences, front-loaded with the main purpose, then return fields, then a practical usage hint. Every sentence provides valuable information with no wasted words.

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

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

For a simple single-parameter list tool with strong annotations, the description is complete: it states the purpose, return structure, and usage scenarios. No additional context seems necessary for correct selection or invocation.

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

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

Schema description coverage is 100% for the only parameter (include_inactive), so the schema fully documents it. The description indirectly reinforces the default behavior but adds no extra 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 clearly states the tool's purpose: 'List the caller's active subscriptions.' It specifies the resource (subscriptions) and scope (caller's active), and differentiates from siblings by focusing on listing vs. subscribing/unsubscribing.

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

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

The description gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It explains when to use the tool, though it doesn't explicitly name alternative tools or state when not to use it.

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

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

Annotations provide no safety hints (all false), so the description carries full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the anonymous claim_token flow, and that it's 'Free; doesn't count against your tool-call quota.' 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?

Though long, every sentence earns its place: purpose, use cases, exclusions, claim_token flow, rate limit, and cost. It is front-loaded with the core action and then layers operational details logically. No redundancy or fluff.

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

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

As a feedback tool with no output schema, the description fully covers what the agent needs: how to file, how to later retrieve resolution, rules about scope, rate limits, and behavior. For the tool's complexity, it is complete and self-contained.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning: explains how claim_token is used to 'read whether it was fixed and what changed,' and instructs message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This goes beyond the schema's per-field definitions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb with explicit resource (Pipeworx team) and differentiates from siblings like ask_pipeworx and discover_tools by positioning itself as a feedback channel.

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 scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives clear exclusions: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context beyond annotations: 'derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data derivation, privacy, and caching behavior, which is meaningful for an AI agent.

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

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

The description is compact and well-structured. It opens with the core purpose, then provides a numbered list of use cases, followed by implementation details. Every sentence earns its place; there is no fluff or repetition.

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

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

Despite lacking an output schema, the description explains what the return contains ('top tools, top packs, and total call volume') and specifies the exact data shape ('just (pack, tool, count)'). Combined with the simple single-parameter interface and rich annotations, this is behaviorally complete for the tool's complexity.

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

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

Schema coverage is 100% with a descriptive enum for the 'window' parameter. The description adds semantic nuance beyond the schema by explaining trade-offs: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches parameter understanding and helps agents choose appropriately.

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: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' This uses a specific verb ('Returns') and distinct resource (trending tool usage), differentiating it from siblings like discover_tools or ai_visibility_check.

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

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

The description explicitly lists three concrete use cases for when to use this tool: discovering hot data sources, confirming canonical choices, and assessing alignment with agent needs. It also contrasts window choices ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not explicitly exclude alternatives or name when-not-to-use, so it lacks the full 'when-not' guidance seen in top-tier examples.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses rich behavioral context: semantic similarity threshold (≥0.30 Jaccard), partition placeholder filter (>20% returns null), and fill check behavior (realizable_edge_pp ≤ 0 means don't trade). This gives the agent critical non-obvious execution details.

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

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

The description is long but well-structured with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Every sentence adds essential information; no filler or redundancy.

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

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

Given the tool's complexity, no output schema, and rich behavioral nuances, the description is remarkably complete. It covers all invocation modes, response field names, edge cases, and fallback reasoning, leaving no major ambiguity.

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

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

While schema coverage is 100%, the description adds substantial meaning: no-args behavior, event vs topic mode semantics, example slugs and seed questions, and acceptance of full URLs. This goes well beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This uses a specific verb and resource, and the methodological details distinguish it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit usage guidance is provided: 'Call with NO args for a `trending_scan`... pass `event` for the strongest per-event partition_check, or `topic` for a themed cross-event scan.' It also names an alternative: 'For custom sizing use polymarket_fill_risk.'

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses rich behavioral detail: caching ('Cached 1h at the KV level keyed on all knobs'), diagnostics for empty segments, the 24h-move warning, the unreliability of Fed signals, and the exact gate thresholds for the longshot segment. This exceeds annotation coverage and provides deep transparency.

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

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

The description is long but well-organized with uppercase segment labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and clear top-level response structure. Every sentence contributes detail; however, the density and length may be overwhelming for quick comprehension. It's structured appropriately for the tool's complexity.

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

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

Despite lacking an output schema, the description fully specifies the response shape (by_segment, fed_candidates/fed_note, _diagnostics), explains the three model families, provides gate thresholds, and describes all knobs. It is comprehensive for a complex tool with 9 parameters and no output schema, covering everything an agent needs 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?

While the schema already documents all 9 parameters (100% coverage), the description significantly enhances meaning. For example, it explains slippage_pp with Polymarket fee context and 20-50bp typical costs, and min_partition_leg_kelly with the parent-level kelly_fraction_half=0 design. This adds actionable knowledge far 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 opening sentence clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This uses a specific verb ('scan'), a resource ('top Polymarket markets'), and an outcome ('return opportunities'), distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on Pipeworx disagreement.

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 frames the tool for 'what should I bet on today' and explains when agents would use it ('without paging hundreds of markets'). It also provides actionable usage context, such as tradeable-edge knobs and a note that Fed opportunities are excluded from ranking. However, it doesn't explicitly name alternative tools or provide when-not-to-use guidance, though the use case 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?

The description goes well beyond the annotations by disclosing the 60-day snapshot TTL, data gaps, decay computed from daily closes (not intraday), and net of default slippage. It also details the response format, including expired opportunities and snapshot dates, fully transparent about 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 long but well-structured with clear sections (purpose, args, response, limits). Every sentence adds value, though it could be slightly tighter. The front-loaded purpose sentence and logical organization earn a high score.

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

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

Given the tool's complexity and the absence of an output schema, the description is exceptionally complete. It explains the response fields (tracked[], expired[], snapshot_dates[]), the meaning of decay_pp_per_day, and the limits, leaving no critical context unaddressed.

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 repeats parameter defaults and meanings without adding significant new semantics. It provides a little context around 'days' and 'window' but not beyond what the schema already explains, 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 uses a specific verb-resource structure: 'Edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?', clearly distinguishing it from siblings like polymarket_edges by focusing on historical decay rather than current edges.

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

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

The description provides clear context for when to use the tool (to distinguish fresh vs. old edges) and explains the rationale ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly name alternatives or state when not to use it, though the reference to 'polymarket_edges snapshots' implies the sibling.

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

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

Even with annotations declaring readOnly/openWorld/idempotent/non-destructive, the description adds substantial behavioral detail: it walks the ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), warns about partial basket fills converting an arb into an unhedged directional position, and names the dominant loss mode. 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?

Although long, the description is densely structured: it splits modes, enumerates return fields per mode, and includes a risk warning. Every sentence contributes operational knowledge — no redundant or filler text. The purpose is front-loaded, and the length is justified by the tool's complexity.

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

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

This complex tool has no output schema, but the description compensates by enumerating all return values for both modes, detailing parameter interpretations, risk caveats, and explicit links to sibling tools. It is complete enough for an agent to invoke correctly and interpret results without additional documentation.

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

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

Schema coverage is 100%, but the description adds crucial meaning: size_usd is explained differently for single-market (max spend on buys, target proceeds on sells) versus basket (settlement notional, shares per leg), includes default and clamp behavior, and clarifies side semantics for both modes. These enrich the schema-led parameter definitions.

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

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

The description opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly identifies the verb 'check' and the resource 'edge vs order-book depth,' and differentiates itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill-risk validation.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the limitation of thin books and the risk of partial fills, providing clear context and alternative tools.

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

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

Beyond the read-only, open-world, idempotent annotations, the description discloses substantial behavioral detail: the logic for comparing bet shapes, the exact conditions that fire compatibility_warning, the meaning of temporal_alignment, and the skipped_cross_type/subtype counters. It even provides concrete examples of non-equivalent bet shapes, which is valuable context for interpreting results.

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 well-structured with capitalized section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and the core purpose front-loaded. Each sentence contributes meaningful detail, though a few clauses could be tightened without losing substance, preventing a 5.

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

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

For a tool with no output schema, the description is remarkably complete: it explains leg-by-leg prices, top_spreads_pp calculation direction, every safety field with trigger conditions, temporal alignment semantics, and practical limitations (pre-mapped ≠ tradeable). An agent would be well-equipped to invoke the tool and interpret its results.

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

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

The schema already covers all three parameters with 100% description coverage, establishing a baseline of 3. The description adds the two-mode framework and explicitly states that explicit parameters override the topic-mapped side, which enriches the interaction semantics beyond the schema alone. The caveat that pre-mapped topics are not necessarily tradeable also informs parameter choice.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which explicitly states the tool's function and differentiates it from Polymarket-only siblings like polymarket_arbitrage. It further specifies the two input modes and response structure, eliminating any ambiguity about what the tool does.

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

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

The description clearly explains when to use the tool (cross-venue spread between Kalshi and Polymarket) and how to use its two modes, topic shortcuts versus explicit ticker/slug. It also warns that pre-mapped topics often return compatibility_warning and are not tradeable, but it does not explicitly name alternative sibling tools for single-venue arbitrage, stopping short of a full when-not/alternatives guide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable scoping behavior ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and clarifies the dual retrieve/list modes. No contradiction with annotations.

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

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

Four sentences, front-loaded with the core functionality, and every sentence contributes unique information (usage, scoping, tool pairing). 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?

The tool is minimal (1 optional parameter, no output schema). The description covers the two return behaviors (value vs. key list), scoping, and how it fits with remember/forget. It omits error details (e.g., missing key behavior), but for this simple tool the coverage is adequate.

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 property description already states 'omit to list all keys.' The description adds only examples of key contents (ticker, address, notes) without new syntactic details, so it meets the baseline but does not significantly exceed 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 and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This clearly distinguishes the tool from its memory-related siblings (remember, forget) by specifying its retrieval and listing role.

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

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

It explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the alternative/complementary tools: 'Pair with remember to save, forget to delete.' This provides clear contextual guidance and exclusions.

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

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

The annotations declare readOnlyHint=true, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which implies a state mutation. This directly contradicts the annotation, so the transparency score is 1.

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 long, front-loaded with the main purpose, and every sentence adds value—return payload, filtering, mark_read behavior, and an alternative endpoint. No unnecessary wording.

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

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

Even without an output schema, the description explains what the returned alerts contain (source, citation_uri, raw payload) and covers key behaviors like filtering, mark_read, and polling. The schema fully documents all parameters, so the description is complete for the tool's complexity.

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

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

The schema already provides 100% parameter descriptions, and the description adds useful semantics beyond it: gives a concrete example for type ('sec_8k'), clarifies the format for since (ISO timestamp), and explains the effect of mark_read. This enriches 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 opens with 'Pull fired events from your subscription feed,' which clearly states the action and resource. It further specifies the return payload (source, citation_uri, raw event payload), distinguishing it from sibling tools like recent_changes or list_subscriptions.

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

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

It provides clear context for when to use the tool (polling a persisted feed) and points to an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It does not explicitly compare against sibling tools, but the guidance is sufficient for most use cases.

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 substantial behavioral context: fan-out to SEC/GDELT/GNews/USPTO, GDELT-to-GNews fallback on rate limits/5xx, USPTO soft-fail due to PatentsView sunset, and the returned structure (changes[] grouped by source, total_changes, citation URIs).

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

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

The description is front-loaded with query examples and packs a lot of necessary detail into a compact paragraph: sources, fallback behavior, date formats, output summary, and alternative tool. The list of six paraphrases is slightly repetitive, but every major clause contributes context, so the length is justified.

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 multi-source tool with no output schema, the description provides sufficient operational detail: exact sources, fallback logic, date semantics, return value summary, and an explicit comparison to entity_profile. An agent can confidently invoke the tool and correctly interpret its result.

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

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

The input schema already covers all three parameters with clear descriptions (type enum, since formats, ticker/CIK formats). The description reinforces the meaning of `since` and connects it to filing windows, but it does not add substantial meaning beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description opens with concrete user intents ('What's new with X', 'latest on Y') and defines the tool as a 'change feed for a company in the last N days/weeks/months' with specific data sources (SEC, GDELT/GNews, USPTO). It clearly distinguishes itself from the sibling entity_profile by contrasting the dynamic feed with a static profile.

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 via example queries and provides an explicit alternative: 'Use entity_profile instead when you want the static profile...'. It also adds practical guidance like choosing '30d' or '1m' for typical monitoring, and mentions the parallel single-call efficiency.

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

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

Adds significant behavioral context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory while anonymous sessions retain for 24 hours. This durability distinction directly impacts how the agent should trust stored data.

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

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

Five short sentences, front-loaded with the primary action. No fluff or redundant information; every sentence earns its place by adding usage, persistence, or companion tool context.

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 write tool, the description covers purpose, usage timing, persistence behavior, and companion tools. No output schema is needed, and the description is complete without missing essential guidance.

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

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

Schema covers both parameters with descriptions and examples (e.g., key format). The description's examples of values ('resolved ticker, target address') reinforce the purpose but do not add new semantics beyond the schema. Baseline 3 is appropriate for high schema coverage.

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

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

The description uses a specific verb phrase 'Save data the agent will need to reuse later' and clearly identifies the resource as a key-value store. It distinguishes itself from siblings by naming recall and forget for retrieval and deletion, making its unique role clear.

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 you discover something worth carrying forward' with concrete examples like 'a resolved ticker, a target address, a user preference'. It also provides companion tool guidance by pairing with recall and forget, which clarifies when to use which tool.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses valuable behavioral traits: unresolved identifiers are explicitly listed rather than omitted, and LEI/FIGI enrichment degrades gracefully, returning EDGAR data even if external sources are down. This surpasses what annotations alone indicate.

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

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

The description is long but information-dense, front-loaded with practical example queries. Nearly every sentence earns its place, though there is slight redundancy between the purpose statement and the 'Use FIRST' directive. For the tool's complexity, this length is justified and well-structured.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, graceful degradation, unresolved handling) and the absence of an output schema, the description covers most essential behaviors. It could be more explicit about the overall shape of the response (e.g., whether a single match or multiple candidates are returned), but it adequately addresses the main use cases and edge behaviors.

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

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

The input schema already documents both parameters with 100% coverage, but the description adds contextual meaning by explaining how the 'type' parameter changes the interpretation of 'value' (ticker/CIK/name vs. brand/generic) and what output to expect per type. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: to resolve a user-spoken name to canonical/official identifiers. It uses specific verbs like 'resolve' and 'look up' with a defined resource (entity names to identifiers), and distinguishes itself from siblings by emphasizing it is the first stop for name-to-ID conversion.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear usage context. It also details supported entity types and their inputs, but lacks explicit when-not-to-use guidance or mention of alternative sibling 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?

The description goes beyond the annotations by explaining that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized entities. It also discloses the return format (score, confidence, signal density), adding valuable behavioral context without contradicting the read-only and idempotent hints.

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

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

The description is three focused sentences with no redundant phrasing. It front-loads the core action and includes a concrete example, making every sentence purposeful.

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 four parameters and no output schema, the description sufficiently covers purpose, usage, behavior, and return value. It gives enough context for an agent to select and invoke the tool correctly, including the ranking mechanism and output fields.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add new parameter semantics beyond the schema; it only reiterates the first-entity-as-subject behavior already documented. No additional guidance on models, apiKey, or context is provided, making 3 appropriate.

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

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

The description clearly states the tool's purpose: comparing AI visibility across multiple entities side-by-side. It specifies the action (compare), the resource (AI presence), and the method (using ai_visibility_check), distinguishing it from the singular ai_visibility_check tool and generic compare_entities.

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

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

It explicitly provides a use case (competitive AI-marketing audits) with an example query, making when-to-use clear. However, it does not explicitly state when not to use this tool or mention exclusions, stopping short of a full 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes beyond by explaining the composite fan-out, the exact output fields, the 5-30s first-measurement delay, and the sources_failed degradation behavior. This adds substantial behavioral context without contradicting the annotations.

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

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

The description is long but well-structured: composite purpose, use cases, return summary, scope limitation, and failure behavior. Each sentence carries necessary information for a composite tool, though it could be slightly more concise 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?

With no output schema, the description thoroughly documents all key return fields, per-advisory details, links, and alternative versions. It also covers ecosystem limitations and partial failure behavior, making the tool sufficiently complete for an agent to use without additional context.

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

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

The input schema already provides full descriptions for both parameters (package name, scoped packages, version default). The description does not add new semantic meaning beyond the schema, so with 100% schema coverage the baseline score of 3 is appropriate.

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

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

The description clearly states a composite 'should I add this npm package to my project' check, naming specific resources (deps.dev and bundlephobia) and the decision it serves. It distinctly positions itself from siblings by focusing on npm packages and aggregating multiple data sources.

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

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

Explicitly instructs when to use ('Use whenever an agent asks...') with concrete examples ('is X safe / popular / small'), and provides exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Also sets expectations for partial failures and timing, guiding appropriate invocation.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds significant behavioral context: it returns top-N passages with character offsets and similarity scores, explains the embedding approach (BGE-base-en, cosine over 500-char overlapping windows), and discloses the 200K char limit with truncation flag. No contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the core purpose and then adding context. Every sentence contributes useful information (use case, pairing, technical details). It is slightly longer than necessary but not bloated, earning a 4 rather than 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?

Despite no output schema, the description clearly explains the return format (top-N passages with character offsets and similarity scores), behavior on long inputs (truncated and flagged), and provides pairing context. It is fully sufficient for an agent to understand what the tool returns and when to use 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 parameters are fully documented in structured form. The description adds some context by explaining text as 'already pulled' and query as natural-language, but this largely repeats the schema's examples and does not go beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with a specific verb ('search') and resource ('within a source'). It distinguishes itself from siblings by emphasizing the 'INSIDE' scope and by directly pairing with ask_pipeworx_grounded for grounding over relevant passages instead of the whole document.

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' and provides a concrete alternative/workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear usage context and exclusions.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses important behavioral traits: authentication requirements (OAuth, anonymous/BYO cannot persist), SMS verification and daily cap, webhook auto-disabling after 10 consecutive failures, and that the webhook signing secret is returned only once. These details add substantial 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 and front-loaded, leading with the core purpose and return value. However, it repeats some details already present in the schema (e.g., SMS verification, webhook signing) and could benefit from bulleted lists for clarity. Overall it is efficient but slightly redundant with the schema.

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

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

Despite the absence of an output schema, the description explains the return value (new subscription id, webhook secret shown once) and covers all subscription types, parameter structures, delivery options, prerequisites, and failure behaviors. It is fully complete for a complex creation tool with nested objects.

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

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

Although the schema already has 100% coverage, the description enriches each parameter with concrete examples and domain context: sec_8k items codes mapping to officer changes, polymarket_edge topics like 'fed', fred_series with series_id, and clinical_trial requirements such as 'sponsor or condition required'. The delivery parameter is also explained with webhook HMAC signing details and email/SMS specifics, going well beyond the schema's property descriptions.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly states the return value (new subscription id) and distinguishes itself from sibling tools like list_subscriptions, recent_alerts, and unsubscribe by focusing on creation and monitoring.

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 establish ongoing monitoring) and includes prerequisites (Pipeworx OAuth account, phone verification for SMS). It also implicitly contrasts with pulling via the always-on feed by noting 'pull via recent_alerts or GET registry.pipeworx.io/alerts.json', but does not explicitly state exclusions or alternatives such as 'for one-time query, use X'. Thus it has clear context but lacks 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?

Annotations already declare readOnly, idempotent, openWorld. The description adds useful behavioral details: returns category-bucketed examples, includes exact tool+argument shapes, and is drawn from the live catalog. This goes beyond what the annotations provide, though it doesn't discuss edge cases or response formatting.

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 packed with valuable information. It front-loads example queries and gets to the point quickly. While the first sentence is a run-on, it effectively communicates the tool's purpose and scope. No wasted words, though a slight structure improvement (shorter sentences) 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 no output schema, the description explains the return content well: category-bucketed questions with tool+argument shapes. It covers inputs, optional parameters, usage scenarios, and expected outputs. For a simple tool with 1 optional param, this is complete and actionable.

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

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

Schema already has a description for topic, but the tool description adds value by giving concrete examples ('finance', 'pharma') and explicitly stating the behavior when omitted ('full spread', 'cross-category spread'). This clarifies the parameter's 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 clearly states it is 'the onboarding entry point' for an agent wanting to know what is worth asking, with specific verbs and resource. It lists example queries and distinguishes itself by explaining its output (category-bucketed questions with tool+argument shapes) and guiding toward meta-tools.

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

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

Explicit guidance is given: 'Call with no arguments for the full spread, or pass topic to focus.' It also says 'Use this FIRST when you do not yet know what Pipeworx can do for you', establishing clear when-to-use. It implies when not to use (once you know, you use other tools) and mentions learning to call meta-tools.

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

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

Beyond the annotations (which indicate a non-read-only, non-destructive action), the description discloses key behavioral details: ownership enforcement, deactivation rather than deletion, and preservation of historical events via 'recent_alerts'. This adds meaningful context beyond what annotations provide.

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

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

The description is two sentences, efficiently front-loaded with the primary action, followed by necessary behavioral context. Every word earns its place; there is no redundancy or filler.

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

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

For a simple one-parameter tool with annotations and a well-described schema, the description covers all essential aspects: the action, ownership constraint, the deactivation behavior, and where to find historical data afterwards. It is 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?

The input schema fully describes the 'id' parameter, including its type and origin ('returned by subscribe'). The description adds no additional parameter semantics beyond 'by id', so the baseline of 3 applies given high schema coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by outlining the cancellation behavior and the deactivation nuance, making it unambiguous.

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

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

The description implies when to use the tool (when you want to cancel a subscription) and provides context about ownership (only your own) and the result (deactivation). It references 'recent_alerts' as the place to view historical events, indirectly pointing to an alternative. However, it lacks explicit 'use this instead of X' guidance, so it doesn't reach a perfect 5.

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

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

The annotations already mark the tool read-only, idempotent, and non-destructive, but the description goes beyond that by explaining the dual pipeline logic, the exact verdict vocabulary, and the nuanced semantics of could_not_verify (failed check, not evidence) vs unsupported (no source cover). This rich behavioral disclosure prevents misinterpretation and is not redundant with annotations.

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

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

The description is dense but well-structured: it front-loads trigger phrases, then clearly explains routing, verdicts, and edge-case warnings. Every sentence earns its place, and the closing 'Replaces 4–6 sequential calls' succinctly conveys the tool's composite value. 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?

Despite lacking an output schema, the description provides a complete picture: what the tool does, when to use it, the two processing paths, the full set of verdict values, the content of the return (value, citation, reasoning), and the critical distinction between could_not_verify and unsupported. This is sufficient for an agent to select, invoke, and correctly interpret the tool's response.

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

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

The input schema has 100% coverage for both parameters (claim with examples, tolerance_pct with default and allowed range). The description reinforces the natural-language nature of the claim and mentions approximately_correct, but it does not add new parameter-specific semantics beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It uses specific verbs like 'verify', 'fact check', and 'confirm or refute' tied to a distinct resource, and it differentiates from siblings by describing the two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for others) and the returned verdict types. This makes the 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and distinguishes between the structured fast path for company-financial claims and the grounded pipeline for all other factual claims. It also provides critical caller guidance on interpreting could_not_verify as 'the check did not happen' and unsupported as 'no source coverage', which is essential for correct usage.

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