Oqmd

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the default free model, the requirement to pass an _apiKey for Anthropic, direct cost implications, and the return structure with per-model fields and a combined view. This goes beyond the safety profile.

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

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

The description is four focused sentences, front-loaded with the primary action and output. It covers default behavior, optional external calls, return format, and use cases without excess. Every sentence adds 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 adequately explains the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers parameters, defaults, costs, and use cases. Minor missing details like what 'confidence' or 'signals' mean are not essential for invocation, so a 4 is appropriate.

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 4 parameters described in the input schema). The description repeats some parameter details (e.g., default model, _apiKey requirement) but does not add much new semantic information beyond what the schema already provides, hence the baseline score.

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 ('Probe one or more LLMs'), the target ('business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes from siblings like scan_competitor_ai_presence by covering any entity, not just competitors, and by explicitly returning per-model scores.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default versus optional Anthropic probing behavior. It does not mention exclusions or explicitly compare to sibling tools, but the context is clear enough for an agent to decide when to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial context: it routes across 5,529 tools/1,455 sources, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and 'one fast call.' It also notes live news routing. This goes beyond annotations, though it doesn't detail rate limits or exact response format, preventing a 5.

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

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

The description is dense but front-loaded: it starts with the most important directive ('PREFER OVER WEB SEARCH') and then explains scope, mechanics, and examples. It's longer than typical but every sentence adds value, including the sibling differentiators and example queries. Slightly verbose for a tool description, but the content justifies the length.

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

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

Given the tool is a general-purpose router answering arbitrary factual questions, the description covers what it handles, how it works, when to use it, when to escalate, and example triggers. It has no output schema, but the description compensates by explaining the return includes structured answers with citation URIs. It also notes works on every tier and is one fast call, addressing practical concerns for an agent.

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

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

Schema coverage is 100% with all six properties described as aliases for the single required 'question' parameter. The description reinforces that the parameter is a natural-language question or request, and provides multiple examples. It doesn't detail formatting requirements (e.g., language, length limits), but given the schema already fully specifies the parameter, the description adds adequate context without needing to restate schema details.

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

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

The description explicitly states the tool is a routing/question-answering tool for authoritative structured data (SEC filings, FDA, FRED/BLS, etc.) with stable citation URIs. It uses specific verbs like 'routes,' 'fills arguments,' and 'returns the structured answer,' and clearly distinguishes itself from siblings like ask_pipeworx_grounded and 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?

Provides explicit guidance: 'PREFER OVER WEB SEARCH,' 'START HERE for most questions,' and 'Step up only when needed' with specific alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). Also includes example trigger phrases and use cases, making it clear when to use this tool vs. 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?

Beyond the annotations, the description adds valuable context: it may have candidate routing improvements enabled live, no candidate is currently active (retired on 2026-07-26), and results are compared against the stable router. It also reassures that it is a full working router, not a fallback stub. This is rich behavioral transparency.

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

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

The description is a bit longer than necessary but each sentence serves a purpose: defining the tool, explaining current state, giving usage guidance, and reassuring it is fully functional. It is well-structured and front-loaded, though slightly verbose.

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

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

Given the absence of an output schema, the description adequately explains the response shape by referencing ask_pipeworx ('same response shape'). It covers purpose, current status, usage, and fallback behavior, making it complete for a tool of this complexity.

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

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

The input schema covers 100% of parameters, including descriptions for the 'question' parameter and all aliases (q, text, input, query, prompt). The description only adds that it has the same arguments as ask_pipeworx, which is useful but does not enhance parameter understanding beyond the schema.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling ask_pipeworx by highlighting its experimental nature and live candidate routing improvements.

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 it exactly like ask_pipeworx when you want the newest routing' and notes that it currently matches ask_pipeworx exactly. It does not explicitly state when not to use it or list alternative tools beyond ask_pipeworx, but the usage context is clear.

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

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

The description adds significant behavioral context beyond annotations: it returns an explicit refusal with reasons like 'not_in_source' and 'data_truncated', and notes the extra LLM call cost. It also clarifies the grounding mechanism and what happens on success/failure.

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 detailed but every sentence earns its place: it explains the mechanism, the output shape, the failure modes, and the tradeoff vs. the sibling tool. It is front-loaded with the core purpose and structured logically.

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 absence of an output schema, the description fully specifies the return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and enumerates all refusal reasons. It also covers cost and alternative recommendations, making it complete for a complex tool.

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

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

Schema coverage is 100%: all six parameters are aliases for 'question' and are fully described in the schema. The description does not add any parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads' and explains it routes like ask_pipeworx but 'EXTRACTS the answer using ONLY what the tool result contains.' This distinguishes it from sibling ask_pipeworx and other 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 usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples, and 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups' clearly states when to choose the alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial transparency: fan-out behavior, resolver contract with match confidence and alternatives, safety mechanisms (low-confidence short-circuit, closed-market status), parent-event extraction, news fallback details, and resolution-rule risk. This goes well beyond the annotations without contradicting them.

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

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

The description is long but well-organized with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. Some redundancy exists (e.g., repeated closed-market handling), but every section provides concrete value for a complex tool, so it earns a 4 rather than 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 comprehensively explains return shapes (market, analysis, evidence), resolver contract, parent_event, news field fallbacks, and status codes. It even covers edge cases like illiquid spreads and cancellation rules, making it highly 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 description coverage is 100% for all 3 parameters, so the baseline is 3. The description provides contextual examples (slug, URL, question text) and explains how include_raw affects response size, but these largely mirror the schema's own parameter descriptions. No significant extra meaning is added beyond the schema, so it stays at baseline.

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

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

The description clearly states the tool's verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the scope (Polymarket bets) and differentiates from siblings by focusing on research/fan-out rather than arbitrage or edge tracking.

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 gives usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly mention when-not-to-use or name alternative sibling tools, but the guidance is clear and sufficient for most selection scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavior context: pulls from SEC EDGAR/XBRL and FAERS, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is longer but every sentence adds indispensable context. It front-loads user-intent examples then explains scope, data sources, and output, with no redundant or filler content.

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

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

Despite lacking an output schema, the description adequately explains return contents ('paired data + pipeworx:// citation URIs per entity'), data sources, and edge-case handling (off-calendar fiscal years). This is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and both parameters have descriptions. The description enriches 'type' and 'values' with concrete examples (AAPL, MSFT, ozempic), clarifies that company values are tickers/CIKs and drug values are names, and explains how results are sorted by primary metric, adding value beyond the schema.

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

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

The description clearly states it performs 'side-by-side comparison of 2–5 companies or drugs' with a specific verb and resource. It distinguishes itself from sequential lookups and aligns with the 'compare' trigger phrases, making its purpose unmistakable.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a direct when-to-use directive and naming the alternative. It also lists multiple query formulations that should invoke this tool.

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

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

The description richly discloses behavior beyond annotations: parallel decomposition across 5,529 tools, return format (findings packet with evidence/confidence/source/fetched_at/citation), gaps[] for unanswered facets ('never invented'), hop field and citation_uri resolvability, contradictions[], semantic excerpting, and latency expectations (15-60s, thorough up to ~90s). This far exceeds what readOnlyHint/openWorldHint/idempotentHint already 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 information-dense and front-loaded (account requirement first, then core purpose), but it is long (several paragraphs, ~300 words) and includes some redundancy (e.g., repeating contradictions[] in the depth parameter and again in the body). Every sentence carries some value, but a tighter structure with bullets or clearer separation would improve scannability.

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 (2 params, no output schema, many behavioral nuances), the description covers key aspects: prerequisites (account), output shape, gaps/contradictions, performance, and depth semantics. It doesn't explain the exact structure of the findings packet in JSON form, but with no output schema the description's narrative outline is reasonably complete. It loses a point for not showing an example response or explicitly listing the fields in a structured way.

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

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

Schema coverage is 100% (both params documented), so baseline is 3. The description adds value by explaining that 'question' can be broad/multi-part ('decomposition is the point') and detailing what each depth level does (quick=3 facets single-hop, standard adds gap recovery + contradictions, thorough is paid with iterative hop). This enriches the enum semantics beyond the schema's concise definitions, but does not fully document cost differences or exact facet behavior 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 specifies a clear verb ('grounded multi-source research'), a resource ('Pipeworx's 1455 STRUCTURED data sources'), and a scope ('broad/multi-part questions'). It explicitly distinguishes itself from siblings by contrasting with ask_pipeworx and search_materials, and by stating 'this is NOT open-web search.'

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

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

The description gives explicit when-to-use ('best for broad/multi-part questions over structured data') and when-not-to-use ('For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). It names alternatives (ask_pipeworx, search_materials) and includes account/tier requirements, which is actionable usage guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses the behavior of returning top-N relevant tools with names, descriptions, and full input schemas, plus curated examples, and that each result is directly callable without a second schema lookup. This adds concrete behavioral context beyond the annotations.

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

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

The description is moderately sized but well-structured, starting with the core purpose, then usage scenarios, then return details, and ending with when to call it. Every sentence provides useful information, though it could be tightened slightly without losing meaning.

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

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

With no output schema, the description adequately explains the return value: it returns top-N tools with names, descriptions, full input schemas, and curated examples. It also explains the 'call first' behavior. For a simple discovery tool with one required parameter, this is complete.

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

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

Schema description coverage is 100%, and each parameter already has a detailed description with examples. The tool description adds little beyond what the schema provides, but it does reinforce the natural-language nature of the query and mentions the limit parameter's role in returning 'top-N'. This matches the baseline of 3 for high coverage.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('Find') and resource ('tools'), and distinguishes itself from sibling tools by framing it as a discovery tool that returns the option set, with the explicit instruction to 'Call this FIRST when you have many tools available.'

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 says when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and explicitly instructs to 'Call this FIRST when you have many tools available and want to see the option set.' It does not mention when not to use it, but the 'FIRST' guidance implies it is preliminary to direct tool use.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses meaningful behavior: it fans out across multiple sources in one parallel call, returns specific data structures, soft-fails on the USPTO PatentsView API due to sunset, uses a GDELT→GNews fallback, and requires zero-padded CIKs. This is far richer than the annotations alone.

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

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

The description is dense but well-structured: it opens with canonical examples, then states the core purpose, usage preference, and returns breakdown. It's slightly long, but every sentence contributes essential details (e.g., patent sunset, fallback, return fields). It could be tightened but remains easily scannable.

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

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

With no output schema, the description fully inventories what the tool returns: cik, company_name, recent_filings with pipeworx URIs, fundamentals from latest 10-K, patents, news via GDELT→GNews, and LEI. It also explains limitations (names unsupported, patent API soft-fail). This is complete for an agent to invoke and interpret results.

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

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

Schema description coverage is 100%, so the description's parameter mentions (ticker or zero-padded CIK, names not supported) exactly mirror what the schema already states. The description adds no new parameter-level meaning beyond the schema, so it stays at the baseline 3.

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

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

The description uses a specific verb phrase ('full cross-source profile') and clearly identifies the resource (US public company) and scope. Examples like 'tell me about X' and 'brief me on Tesla' make the purpose unmistakable. It also distinguishes itself from sibling tools by explicitly preferring it over chaining single-pack lookups and pointing to resolve_entity for name-only inputs.

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

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

The description gives explicit when-to-use context: when the user asks for a holistic view of a company ('tell me about X', 'research Acme', etc.). It also states when not to use it (names are not supported, use resolve_entity first) and names an alternative (single-pack SEC/XBRL/news lookups) that should not be chained when this tool is preferred.

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 readOnlyHint, so the bar is lower. The description adds the memory context and sensitive data nuance, consistent with annotations, but doesn't reveal additional behavior beyond what is already known.

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, action first, zero filler. 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?

With a single parameter, complete schema, and clear annotations, the description covers all necessary selection and invocation context. It could mention irreversibility, but the destructiveHint annotation already covers that.

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

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

Schema coverage is 100%, so baseline is 3. The description only says 'by key' and adds no extra meaning beyond the schema's 'Memory key to delete'.

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 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself from siblings by explicitly mentioning pairing with remember and recall.

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

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

The description gives explicit when-to-use guidance: stale context, task done, or clearing sensitive data. It also references companion tools, providing context, though it lacks when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety traits. The description adds valuable process context: fetching the page, extracting content, and emitting markdown. It also clarifies the output is a single text blob. It does not discuss edge cases (e.g., inaccessible URLs) but adds meaningful transparency beyond annotations.

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

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

The description is three sentences, front-loaded with the core action, and contains no fluff. Every sentence contributes purpose, process, or 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 2-parameter tool with no output schema, the description explains inputs, process, output format, and use cases. It does not mention error handling or limitations, but it covers the essential information needed to use the tool effectively.

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

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

Schema description coverage is 100%, with both parameters clearly documented. The description does not add extra parameter-specific details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It explains the process (fetches, extracts, emits) and distinguishes itself from all sibling tools by describing a unique function. The use cases further reinforce its purpose.

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

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

The description provides explicit 'Useful for' scenarios, which give clear context on when to use the tool. However, it does not mention alternative tools or when NOT to use it, so it stops short of full exclusionary 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, and non-destructive. The description adds useful behavioral context such as 'Keyless' (no auth needed) and enumerates the return fields, which goes beyond the annotations. 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?

Two sentences, with the purpose front-loaded, followed by a compact list of return fields and a keyless note. Every word earns its place with zero waste.

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

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

For a single-parameter, read-only material fetch, the description covers what it returns, the key type, and authentication status. The absence of an output schema is mitigated by the enumerated return fields, making it complete for this low-complexity tool.

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

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

Schema coverage is 100%, so the schema already documents entry_id thoroughly with an example and source guidance. The description's example (16525) adds a tiny bit of context but largely duplicates the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool 'Fetch a single OQMD material by its entry_id' with a concrete example, distinguishing it from search-like siblings such as search_materials. The verb+resource+key is specific and unambiguous.

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

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

The description and schema together imply usage context: you need an entry_id from previous search results, as stated in the parameter description ('Get ids from search_materials results'). However, it doesn't explicitly contrast with alternatives like stable_phases, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond these by noting it lists the caller's own subscriptions and specifying the default behavior (active only). This is useful behavioral information not present in the annotations.

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

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

The description is exactly two sentences: the first states the action, resource, and return fields; the second gives usage guidance. Every sentence contributes value, and the structure is front-loaded with the most important information.

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

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

The tool is simple, with one optional parameter and no output schema. The description covers the action, scope, return fields, and practical usage scenarios. Combined with the annotations, it gives an agent everything needed 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 schema has 100% coverage for the single include_inactive parameter, including its default value. The description does not add extra meaning beyond the schema; it only implies the default behavior. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions.' It distinguishes the tool from sibling actions like subscribe/unsubscribe and enumerates the returned fields, making the purpose unambiguous.

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

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

It explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' giving concrete scenarios for usage. However, it does not explicitly state when not to use it or name alternatives like subscribe/unsubscribe, so it falls just short of a 5.

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

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

Even though annotations provide no hints (all false), the description discloses key behaviors: returns a claim_token when filing without an account, allows later lookup with that token, and includes 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' This goes well beyond the annotations.

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

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

The description is packed with necessary information and front-loaded with the core purpose. However, sentences like 'The team reads digests daily and signal directly affects roadmap' are motivational rather than essential for tool invocation, keeping it from a 5.

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

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

For a tool with no output schema and moderate complexity (4 params, nested object), the description covers all necessary guidance: what to report, how to scope feedback, the token mechanism, rate limits, and exclusions. It is fully self-contained and leaves no significant 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%, so the baseline is 3. The description adds value beyond the schema by explaining how claim_token is used ('Filing without an account returns a claim_token; pass it back later...') and by instructing on message content ('don't paste the end-user's prompt'). This raises it to a 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the verb and resource. It also distinguishes itself from siblings by specifying it is for feedback about Pipeworx tools only, not other MCP servers.

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 conditions: '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).' It also gives an explicit exclusion: '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, idempotentHint, and non-destructive behavior. The description goes further by revealing it is a self-aggregating signal derived from CF analytics-engine, guaranteein no PII (only pack, tool, count), and explaining caching behavior (5min-1h). This adds meaningful context about data provenance, privacy, and freshness beyond the structured annotations.

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

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

The description is compact and efficient: a clear hook, explicit outputs, a numbered list of use cases, and a final sentence on data source, privacy, and caching. Every sentence earns its place, and the structure makes it easy to scan.

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

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

With only one optional parameter, no output schema, and comprehensive annotations, the description covers core behavior, use cases, data provenance, privacy, and freshness. The agent receives enough context to decide when and how to invoke the tool without needing additional 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?

The single 'window' parameter is fully documented in the schema with enum values and a description of the trade-off between short and long windows. The main description only repeats '24h, 7d, or 30d' without adding extra semantic meaning, so the schema carries the weight, and 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 opens with a clear question ('What other AI agents are calling on Pipeworx right now') and then specifies the returned content (top tools, top packs, total call volume) over selectable windows. This clearly distinguishes it from sibling tools like discover_tools or ask_pipeworx by focusing on aggregated agent call trends.

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

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

The 'Useful for' list provides three concrete scenarios (discovering hot data sources, confirming a canonical tool, aligning with agent demand), giving clear context on when to use it. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Despite annotations already indicating readOnlyHint=true and idempotentHint=true, the description goes far beyond by detailing internal checks (semantic anchor requiring ≥0.30 Jaccard similarity, partition filter dropping placeholder slugs), response structure, and the fill check caveat: 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' This is rich behavioral context that is not present in annotations.

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

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

The description is long but well-structured with explicit section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every section adds necessary detail. It could be slightly tighter without losing critical caveats, so it earns 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?

Given the tool's complexity (three modes, multiple filters, and a fill check) and the absence of an output schema, the description fully compensates by detailing response fields, the partition_check object, and the fill-check pricing logic. It also directs users to polymarket_fill_risk for custom sizing, covering the full usage context.

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

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

Schema coverage is 100%: both 'event' and 'topic' have descriptions in the schema. The tool description adds value by explaining the mode selection rationale (which to use when), providing example slugs and seed questions, and clarifying that full URLs are accepted. This goes beyond the schema's brief descriptions, earning a 4.

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

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

The description opens with a specific, non-tautological statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by naming the arbitrage focus and three distinct modes (trending_scan, event, topic), and even references polymarket_fill_risk for custom sizing, which separates it from that sibling.

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: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)', along with concrete examples. It also states when NOT to use the tool: 'For custom sizing use polymarket_fill_risk.' Additionally, it explains why cross-event mode is valuable and what it catches that single-event misses.

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 context: the three-segment output structure, the five model families and their assumptions, the 24h-move warning ('your edge may already be in the price'), caching behavior, and the diagnostics funnel. This goes far beyond what annotations convey.

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

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

The description is long but front-loaded with a clear purpose. It uses structured segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and logically organizes knobs and response fields. While dense and containing long parenthetical asides, it is appropriately sized for a tool with 9 parameters and complex output semantics.

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

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

There is no output schema, so the description must explain return values. It does so thoroughly: the by_segment structure, opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread_pp), diagnostics funnel, and cache keying. It also explains the rationale behind exclusions and design decisions, making it a complete description for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by grouping knobs as 'TRADEABLE-EDGE KNOBS', explaining how min_partition_leg_kelly applies per-leg while parent-level Kelly is zero, and contextualizing slippage_pp with Polymarket fee information. This enriches understanding beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly states the tool's purpose and even names the intended use case ('what should I bet on today'). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, even though alternatives are not explicitly named.

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 'Built for "what should I bet on today"' and explains the benefit of discovering opportunities without paging hundreds of markets. It also provides exclusion reasoning for Fed bets and detailed guidance on when to adjust knobs like min_liquidity and max_spread_pp. It lacks an explicit 'use this instead of X' statement but the contextual guidance is strong.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds meaningful behavior details beyond annotations: 60-day snapshot TTL, snapshot gaps on cache-miss, computation on daily closes rather than intraday, and lifespan as a competition clock. No contradictions with annotations.

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

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

The description is long but highly structured with labeled sections (Args, RESPONSE, LIMITS) and no filler or repetition. Each sentence adds unique information about purpose, parameters, response structure, or limitations, making the length 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?

With no output schema, the description fully compensates by detailing the response shape (tracked[], expired[], snapshot_dates[]) and field meanings. It also covers edge cases like snapshot gaps, TTL constraints, and computation methodology, making the tool predictable for an agent.

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

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

Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description adds value by explaining the practical role of 'days' (lookback) and 'window' (snapshot family) and clarifying defaults ('default 14', 'default 1wk'), slightly extending the schema's clamp range detail.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It distinguishes itself from sibling polymarket_edges by emphasizing historical tracking across snapshots 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 gives strong contextual guidance ('a fresh wide edge and a 3-week-old wide edge are different trades') and explains when the tool is relevant for evaluating opportunities. It references polymarket_edges as the source but does not explicitly name alternative tools or state when not to use this tracker.

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 destructiveHint=false, but the description goes far beyond by disclosing exactly how the tool simulates fills: walking the order book ladder, returning fill metrics (top_of_book, vwap_fill_price, slippage_pp), computing basket-level capture_ratio, and explicitly warning about thin_legs and forced_directional_risk. It explains partial-fill risks and why the tool exists, which is meaningful behavioral context beyond annotations.

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

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

The description is information-dense but well-structured, with the core purpose in the first sentence, followed by REQUIRES, then clear SINGLE-MARKET and BASKET sections, and ending with a prescriptive 'USE THIS' rule. Every sentence earns its place; no filler. Despite its length, the complexity of two modes justifies the detail.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly lists single-market returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket returns (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers edge cases like thin legs and partial fills, making it complete for a complex dual-mode 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?

Even though schema coverage is 100%, the description enriches every parameter with mode-specific meaning. For example, size_usd is detailed as 'max spend on buys, target proceeds on sells' in single-market mode, and as 'settlement notional — shares per leg' in basket mode. It also clarifies side defaults (buy_yes or auto-detect from partition sum) and the interpretation of market vs event. This adds real semantic depth 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 precise, specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and references sibling tools (polymarket_arbitrage, polymarket_edges), so an agent can immediately understand what this tool does and how it differs.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills create unhedged positions), covering the 'when' clearly and implicitly defining the 'when not' (small trades or where full execution is guaranteed).

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

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

The description goes far beyond the annotations, detailing edge-case behaviors such as compatibility_warning triggers (matched_pairs:0 with skipped_cross_type>0 vs. semantically unrelated events), temporal_alignment meaning, and skipped_cross_type/subtype interpretations. It also explains the response structure and the significance of non-equivalent bet shapes. This comprehensive disclosure makes the tool's behavior highly predictable.

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 bolded section headers ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS') and a clear hierarchy. The opening sentence front-loads the core purpose, and every subsequent sentence adds specific, non-redundant information. While dense, the length is justified by the tool's complexity; no wasteful fluff is present.

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

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

With no output schema available, the description bears the full burden of explaining the response format, and it does so thoroughly: leg-by-leg prices, spread computation, compatibility_warning cases, temporal_alignment, and skip counters. It even warns about the current reliability of pre-mapped topics. This makes the description nearly self-sufficient for invocation and interpretation.

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

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

The schema already provides descriptions for all three parameters with 100% coverage, listing valid topic values and example formats. The tool description adds value by explaining the interaction between parameters: how topic auto-fetches events, how explicit ticker/slug overrides the topic mapping, and how the two modes relate. This supplements the schema's individual parameter definitions with usage semantics.

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

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

The first sentence explicitly states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes it from sibling tools like polymarket_arbitrage (which focuses on single-venue arbitrage) by specifying the cross-venue comparison between two distinct platforms. The description further clarifies the two modes (topic shortcuts and explicit pairings), leaving no ambiguity about what the tool does.

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

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

The description clearly explains the two usage modes: using a pre-mapped 'topic' or explicit ticker/slug pairings. It also provides crucial guidance on when the tool's output is meaningful, emphasizing that equivalent bet shapes are required for a real signal and warning that most pre-mapped topics currently return compatibility_warning. It doesn't explicitly name alternative tools for comparison, but the usage context is well defined.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving vs. listing all keys. It does not detail edge cases like missing key behavior, but annotations cover the safety profile.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value: function, use case, scoping, and relationship to sibling tools. No redundant or filler content.

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

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

The tool is simple (1 optional parameter, no output schema). The description sufficiently covers behavior, scoping, and usage. While the exact return format is not specified, for a memory retrieval tool it is implicitly whatever was saved, and the list behavior is mentioned. Overall adequate and complete.

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

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

Schema coverage is 100% with the key parameter clearly described as 'omit to list all keys'. The description reinforces this behavior and adds concrete examples of typical key values (target ticker, address, research notes), providing semantic context beyond the schema.

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

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

The description clearly states the tool's function: retrieve a previously saved value or list all saved keys. It uses specific verbs and identifies the resource (saved memory via remember). It also distinguishes itself from siblings by explicitly referencing remember and forget.

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

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

It provides explicit context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also notes the alternative of omitting the key to list all keys and mentions pairing with remember (save) and forget (delete).

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

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

Annotations declare readOnlyHint:true, but the description explicitly says mark_read:true 'flag[s] returned events read so the next call only shows newer ones'—a persistent side effect. This directly contradicts the read-only annotation, so despite rich behavioral detail, the contradiction forces a score of 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 front-loaded with the purpose and uses a few well-structured sentences. Each sentence contributes useful details (return fields, filtering, mark_read behavior, HTTP alternative), though the last sentence about the registry URL could be seen as slightly tangential for the tool's core use.

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 5 optional parameters and no output schema, the description adequately explains the return items, filtering options, mark_read side effect, and even provides an external endpoint. It doesn't cover limit or unread_only, but the schema fills those gaps; the contradiction with annotations keeps it from a 5.

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

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

The schema already covers all 5 parameters with descriptions, so baseline is 3. The description adds value by giving an example type ('sec_8k'), explaining the since parameter as an ISO timestamp, and clarifying that mark_read causes the next call to return only newer events—semantic nuance 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 ('Pull') and resource ('fired events from your subscription feed'), and clearly states the return payload. It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired alerts from the evaluator's feed.

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

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

The description gives clear context: it's for pulling recent alerts, supports polling, and mentions an HTTP alternative for scripts/dashboards. However, it doesn't explicitly contrast with sibling tools or state when not to use this tool, so it falls just short of full guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO with a soft-fail note), and specifies the return structure (changes[] grouped by source + total_changes + citation URIs). It also explains the fallback conditions (rate-limited or 5xx) and the API sunset, which are important behavioral traits not captured in annotations.

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

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

The description is dense but well-organized, front-loading with query examples before the core definition. The middle section packs source details, fallback behavior, and date formats, and the final sentence provides the sibling-tool pointer. While the initial example list is somewhat redundant, every sentence earns its place given the tool's complexity; a 4 reflects minor excess but strong structure.

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

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

Given there is no output schema, the description compensates by specifying the return payload (structured changes[], total_changes, pipeworx:// citation URIs). It also covers edge cases (GDELT→GNews fallback, USPTO soft-fail until reactivated) and clarifies the `since` window formats. For a tool with three required parameters and this complexity, the description is complete enough to guide correct invocation and expectation-setting.

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 descriptions for all three params. The description adds substantial extra meaning for `since` by giving concrete formats (ISO date or '7d', '30d', '3m', '1y') and a recommendation ('Use 30d or 1m for typical monitoring'), which goes beyond the schema's phrasing. The other parameters are already well-described in the schema, so the description adds marginal but useful context.

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

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

The description opens with a list of natural-language query examples and then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly differentiates from the sibling entity_profile by directing users to that tool for static profiles, making the purpose unmistakable.

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

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

The description explicitly gives when-to-use cues (queries like 'what's new with X', 'latest on Y') and provides an explicit alternative: 'Use entity_profile instead when you want the static profile...'. It also offers parameter-level guidance, recommending '30d' or '1m' for typical monitoring. This is clear usage guidance with 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?

Descriptions adds significant behavioral context beyond annotations: storage is 'scoped by your identifier', authenticated users get persistent memory, anonymous sessions retain for 24 hours. This exceeds the safety flags and gives the agent critical persistence semantics.

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 sentences, each earning its place: opening purpose, when to use, storage model, persistence details, and sibling pairing. Front-loaded with the verb and resource, 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?

For a simple two-parameter tool with no output schema, the description fully covers purpose, usage, storage behavior, and related tools. No gaps remain for the agent to safely invoke this tool.

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

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

Input schema already covers 100% of parameters with descriptions and examples. The description reinforces these with additional use-case examples but does not add new semantic meaning beyond the schema. Baseline of 3 applies.

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

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

The description clearly states the action: 'Save data the agent will need to reuse later' and identifies the resource as key-value memory scoped by identifier. It also distinguishes from siblings by explicitly pairing with 'recall to retrieve' and 'forget to delete', making the tool's role unambiguous.

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

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

Provides explicit when-to-use context with concrete examples ('a resolved ticker, a target address, a user preference') and explains the benefit ('so you don't have to look it up again'). It names alternatives (recall, forget) but lacks explicit when-not-to-use exclusions, preventing a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description's addition of graceful degradation (LEI/FIGI enrichment falls back to EDGAR if GLEIF/OpenFIGI unavailable) and the explicit reporting of unresolved identifiers under `unresolved` provides valuable context beyond the annotations. It also describes internal cascading behavior, which is useful for understanding latency or potential failures.

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

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

The description is longer than average but well-organized: it opens with example queries, states the core purpose, then details supported types and behavioral caveats. Each sentence adds necessary information, especially given the two entity types and multiple identifiers involved. It could be slightly more concise, but 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?

Since there is no output schema, the description fully explains what is returned for each type: for company, it lists CIK, ticker, company_name, LEI with ownership, and FIGI, plus the `unresolved` field; for drug, it mentions RxCUI, ingredient, brand, and citation. It also covers degradation behavior, making it comprehensive for the tool's complexity.

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

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

The input schema covers both parameters with descriptions, but the description adds meaningful examples and clarifications, such as the exact formats for company values (ticker, CIK, or name) and the inputs/outputs for drug resolution. It also explains that LEI/FIGI enrichment is conditional on resolution, which adds semantic depth beyond the schema.

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

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

The description explicitly states the tool resolves a user-spoken name to canonical/official identifiers, with specific examples like 'What's the ticker for...' and 'look up the ID for...'. This clearly distinguishes it from sibling tools such as entity_profile or compare_entities, which serve different purposes. The verb 'resolve' and resource 'entity name to identifiers' are specific and 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?

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' This clearly indicates when to use it. It also implies the tool is a preliminary step for other tools, but it does not name specific alternative tools or explicitly state when not to use it, so it stops short of a 5.

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

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

With annotations already declaring the tool as read-only, idempotent, and non-destructive, the description adds meaningful behavioral context: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations and gives insight into the tool's internal methodology and output, though it doesn't disclose potential rate limits or error 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 three sentences, front-loaded with the core action, and includes a concrete example. Every sentence adds value—stating the function, the underlying mechanism, a use case, and the return format—with 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?

Despite having no output schema, the description covers the return format (ranked list with score, confidence, signal density). Combined with the schema's full parameter documentation and annotations covering safety, the description provides a complete picture for an agent to invoke the tool correctly. It doesn't mention edge cases like rate limits or failure handling, but these are less critical given the tool's read-only nature and the provided context.

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

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

Schema description coverage is 100%, with detailed parameter descriptions (e.g., 'First entry treated as the subject...' for entities). The description adds minor semantic reinforcement by framing entities as 'your brand + N competitors' and mentioning the probe mechanism, but it doesn't significantly augment what the schema already provides. 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 compares AI visibility across multiple entities, with a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It distinguishes itself from the sibling ai_visibility_check by explicitly saying it probes each entity with that tool and ranks results, making the purpose unmistakable.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example query, effectively conveying when to use the tool. It indirectly references the alternative ai_visibility_check by explaining this tool probes each entity with it, but it doesn't explicitly state when not to use it or name other alternatives like compare_entities, 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?

Beyond the annotations (readOnly, idempotent), the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and the sources_failed field will indicate timeouts. This is important operational 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 dense but well-structured: purpose, usage, return value summary, ecosystem scope, and failure behavior each get a sentence. No wasted words; all information 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?

Given the tool's complexity (composite of two external APIs) and no output schema, the description covers the key return fields, per-advisory details, links, version alternatives, ecosystem limits, and partial failure semantics. This is sufficient for an agent to understand what to expect.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add much beyond the schema: it reiterates npm package name and default version behavior, but adds no new parameter-specific semantics. The latency note for new versions is a minor addition.

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

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

The description clearly states the tool's purpose: a composite check for 'should I add this npm package to my project', combining deps.dev and bundlephobia data. It uses a specific verb ('scan'), names the resource (npm package), and distinguishes from siblings like scan_competitor_ai_presence.

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

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

Explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides an exclusion: for non-NPM ecosystems, it directs to use deps.dev:version directly, giving clear alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context by listing specific returned fields (formation energy, hull distance, band gap, space group, prototype), clarifying keyless access, and specifying the input constraint. No contradiction.

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

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

Three tight sentences: purpose, return fields, and key constraint. No filler, front-loaded with the most important information.

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

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

For a search tool with no output schema, the description covers what is returned, how to filter, and input requirements. Minor gaps like sort order or default limits are not critical since limit is in the schema.

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

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

Schema coverage is 100% and each parameter is well described. The description adds the decisive 'at least one of composition or element_set' rule and explains the meaning of the stability filter in terms of convex hull distance, which enriches the schema's flat descriptions.

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

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

The description uses a specific verb 'Search' with an explicit resource (Open Quantum Materials Database) and identifies query dimensions (composition, elements) and filters. This clearly distinguishes it from siblings like get_material (likely retrieving by ID) and stable_phases.

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?

States a clear prerequisite: 'Provide at least composition or element_set', and notes keyless access. It doesn't explicitly name alternative tools, but the usage context is clear from the description.

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

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

Beyond the readOnly/idempotent hints, the description discloses technical specifics: 'BGE-base-en embeddings + cosine over 500-char overlapping windows', a 200K-char limit with truncation flagging, and that the output includes 'character offsets and similarity scores' so the agent can verify verbatim quotes. These details add significant transparency and no contradictions with annotations.

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

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

The description is dense but well-structured: main purpose first, then usage context, then implementation details. Every sentence adds value, though the length is slightly more than necessary. The section on embedding/window mechanics could arguably be condensed, but it's relevant for behavioral transparency.

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

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

With no output schema, the description compensates by explaining what is returned (passages with offsets and similarity scores), the constraints (character cap), and how it fits into a larger workflow. It is complete for an agent to use effectively without further 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?

The schema covers 100% of parameters with detailed descriptions (e.g., query examples and limit range). The description adds marginal context (e.g., 'text you already pulled') but largely repeats schema information. It does not meaningfully enrich parameter understanding beyond the baseline.

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

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

The description uses a specific verb ('Semantic search INSIDE a fetched record') and clearly identifies the resource (a record's text). It distinguishes from sibling tools by emphasizing the 'already pulled' text and the search-within behavior, contrasting with global tools like search_materials.

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

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

Explicit usage guidance is provided: 'Use when the record is too big to cram into the prompt' and it names an alternative/complement (ask_pipeworx_grounded) with a concrete pattern: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This clearly tells the agent when to use it and how it pairs with a 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?

Despite annotations already marking readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral context: the stability criterion (<= ~0), the exclusivity of elements, and the 'Keyless' access. This goes well beyond the annotations and informs the agent about filtering behavior and authentication needs.

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

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

The description is two sentences: the first states the purpose and gives an example, the second adds constraints. Every sentence earns its place, and it is perfectly front-loaded. 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 has no output schema, but the description provides a concrete example of return values (FeO, Fe2O3, Fe3O4), states the selection criteria, and mentions 'Keyless'. Combined with strong annotations, this is fully complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'elements' parameter meaning with an example and emphasizes 'ONLY', but it does not add new syntax, formatting details, or limit constraints beyond what the schema already provides.

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

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

The description clearly states the tool lists ground-state (on-hull) phases of a chemical system, with a specific verb ('List'), resource ('phases'), and scope ('thermodynamically stable compounds in OQMD'). The example ('Fe-O' returns FeO, Fe2O3, Fe3O4) solidifies understanding and distinguishes this from sibling tools like search_materials.

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 this tool: to retrieve stable phases for a given element set. It adds the key constraint 'materials made ONLY of the given elements' and notes 'Keyless' (no auth). However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Goes well beyond the annotations by disclosing auth requirements, delivery channel behavior, SMS caps, phone verification, webhook HMAC signing, one-time secret return, and auto-disable after 10 consecutive failing runs. 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?

Although lengthy, every sentence contributes necessary information. The description front-loads the core action and return value, then organizes types, delivery, and requirements in a logical, scannable manner.

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

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

Given the tool's complexity (multiple types, nested params, optional delivery channels), the description covers all critical aspects: use cases, prerequisites, parameter examples, delivery details, error conditions, and return value. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing real-world examples (e.g., items:["5.02"] for officer change, series_id:"UNRATE") and explaining the semantics of each type and delivery option 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation, and it enumerates the supported subscription types.

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 strong context for when to use the tool (proactive monitoring) and prerequisites (OAuth account, verified phone for SMS), but does not explicitly contrast it with alternatives like list_subscriptions or recent_alerts. The differentiation is implied rather than stated.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds behavior beyond that: it returns category-bucketed examples 'drawn from the live catalog of thousands of tools' and notes that each example includes the exact tool + argument shape. This immediately communicates the tool's open-world, advisory nature 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 every sentence carries meaningful information: entry-point purpose, example queries, return structure, parameter options, and explicit first-use guidance. It is front-loaded with example user questions, making the tool's intent instantly recognizable, and remains dense without redundancy.

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

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

Given the tool's open-ended onboarding role and lack of an output schema, the description is fully complete: it explains what output to expect (category-bucketed examples with tool+argument shape), how to adjust scope (topic vs. no args), and when to use it (first contact, meta-tool learning). No critical use-case information is missing.

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

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

Schema description coverage is 100%, and the schema already explains `topic` as an optional focus area with a list of values and the omit-for-spread behavior. The description's mention of 'e.g. finance, pharma, betting' adds small illustrative value but does not fundamentally extend the schema semantics; the description and schema essentially say the same thing.

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

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

The description clearly identifies the tool as the onboarding entry point for a newly connected agent, with specific verbs ('Returns category-bucketed example questions') and resource ('example questions... with the exact tool + argument shape'). It distinguishes itself from siblings by stating 'Use this FIRST' and by focusing on the discovery of what Pipeworx can do, rather than executing a specific query.

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 when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides usage variants: 'Call with no arguments for the full spread, or pass `topic`... to focus'. It names alternative meta-tools (ask_pipeworx, entity_profile, compare_entities), giving clear guidance on this tool's role.

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

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

The description adds significant behavioral detail beyond the annotations: ownership enforcement, deactivation instead of deletion, and the link to historical events via 'recent_alerts'. This complements the annotations (destructiveHint=false, idempotentHint=true) without contradicting them, giving the agent a clear picture of side effects.

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

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

The description is two sentences, front-loaded with the core action ('Cancel a subscription by id'), followed by two high-value behavioral notes. 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?

For a single-parameter tool with no output schema, the description covers the essential aspects: what it does, who can use it, and what happens to the data. It also references 'recent_alerts' for post-cancellation visibility, making the behavior predictable. The annotations enrich this further, so the tool is fully specified for an agent.

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

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

The schema already describes the 'id' parameter completely ('Subscription id (uuid) returned by subscribe'), achieving 100% coverage. The description only says 'by id', adding no new meaning. Per the rubric, high schema coverage yields a baseline of 3, and no extra parameter insight is provided.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Cancel a subscription by id.' This distinguishes it from sibling tools like 'subscribe' (create) and 'list_subscriptions' (query). The action is unambiguous and directly tied to the tool name.

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

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

The description implies the usage context: use when you need to cancel a subscription, and clarifies ownership constraints ('you can only cancel your own subscriptions'). It also indicates a key consequence (deactivation, not deletion). However, it does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Extensive behavioral disclosure goes far beyond the annotations: it explains the verdict types, the meaning of 'could_not_verify' (with verification_error and that it is not evidence), and 'unsupported'. This adds critical context for interpreting results, which the readOnlyHint/openWorldHint annotations do not convey.

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

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

The description is long but densely packed with essential information: query examples, the financial-vs-other path, verdict meanings, and caveats. It is well-structured and front-loaded with usage triggers, though it could be slightly tightened 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?

For a tool with no output schema, the description thoroughly explains the return values (verdicts, actual value, citation, reasoning) and error states (could_not_verify vs unsupported). It also notes the efficiency gain over multiple sequential calls, making it fully contextual for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic value by explaining how tolerance_pct overrides the claim's implied tolerance and suggesting specific values for hallucination detection, which is not fully captured in the schema's parameter description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with examples of query phrasing. It distinguishes itself from siblings like deep_research or bet_research by focusing on fact-checking, and explicitly differentiates between company-financial claims (via SEC EDGAR) and other factual claims.

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 whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. It also explains that non-financial claims fall through to a grounded pipeline, but it does not name alternative sibling tools or explicitly state when not to use this tool, earning a 4 rather than a 5.

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