Pipeworx

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

Discloses key behavioral traits beyond annotations: default model (Workers AI free), optional Anthropic probing requiring BYO key (cost implication), and return format (per-model + combined view). 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?

Very concise—3-4 sentences front-loaded with action and result, then essential details. 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?

Sufficiently complete given no output schema: explains purpose, usage, return format, and key constraints. Minor gaps (e.g., error handling) but acceptable for 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?

Schema has 100% description coverage, but description adds value by explaining default model behavior and the conditional need for _apiKey. Enhances understanding of parameter interactions beyond schema alone.

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

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

Description clearly states the tool probes LLMs to score visibility (0-100) per model, with specific verb 'probe' and resource 'LLMs'. It distinguishes from siblings like ask_pipeworx by focusing on AI visibility audits rather than general Q&A or 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?

Provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs. optional model usage. No explicit when-not-to-use or alternatives, but context is sufficient.

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, and the description adds valuable context about routing to sub-tools, returning citation URIs, and being 'one fast call' on every tier. While it doesn't mention potential failure modes or rate limits, the description's disclosure of its meta-behavior (routing to tools) goes beyond the annotations without contradicting them.

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

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

The description is longer than ideal but well-structured: it leads with the most critical instruction (prefer over web search), then explains what it does, provides use cases and examples, and ends with alternatives. Every sentence adds information, though some phrases ('even if web search could also answer it') are slightly redundant with the opening.

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 only one required parameter, the description is remarkably complete. It covers purpose, usage triggers, alternatives, expected output format (structured answer with citation URIs), performance characteristics (one fast call), and compatibility ('works on every tier'). No critical information is missing.

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

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

Schema coverage is 100%, and the description adds examples of valid questions ('current US unemployment rate', 'Apple's latest 10-K') that illustrate how to formulate the single required parameter. This goes beyond the schema's generic 'question' description, but the added value is somewhat moderate since the examples also appear in the schema.

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

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

The description clearly states the tool's function: routes questions to the right tool among 5,529 tools and returns structured answers with citations. It uses a specific verb ('routes') and resource ('5,529 tools'), and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

Explicit guidance is provided: 'PREFER OVER WEB SEARCH' sets the primary use case, 'START HERE for most questions' establishes it as default, and concrete alternatives (ask_pipeworx_grounded, deep_research) are named with clear 'step up only when needed' instructions. This is exemplary 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?

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, the description adds important dynamic context: candidate routing improvements are enabled live, none are active right now with a retirement date, and it 'falls back to nothing' because it is a full working router. This goes well beyond 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 four sentences, front-loaded with the core identity, and every sentence adds useful information: beta status, current state, usage direction, and the no-fallback caveat. It is dense without being wordy.

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

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

The description covers beta status, current equivalence, usage intent, and comparison to the stable router, and explicitly states the same response shape. However, because there is no output schema, it relies on knowledge of ask_pipeworx for exact return details, making it slightly incomplete as a standalone definition.

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

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

The input schema covers all six parameters with 100% coverage; each alias is clearly described as an alias for question. The description only says 'same arguments' without adding new parameter-level meaning, so the schema carries the full burden and baseline 3 is appropriate.

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

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

Description clearly identifies the tool as a beta version of ask_pipeworx and states it is a universal router with the same 5,529 tools and arguments. It differentiates from the stable sibling by explicitly mentioning live candidate routing improvements, making the purpose and scope obvious.

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 results are compared against the stable router. It gives clear context for when to use the beta variant, though it does not explicitly state when not to use it or name non-ask_pipeworx 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: it uses ONLY tool result content, may return explicit refusals with specific refusal_reason values, and costs an extra LLM call. It also exposes the refusal mechanism, which is a critical behavioral trait beyond the annotations. No contradiction found.

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: purpose, mechanism, return format, usage cases, and cost trade-off are presented in a logical flow. Every sentence adds new information; there is no filler. It is front-loaded with the core concept and uses structured elements like the return shape and refusal reason list efficiently.

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

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

For a complex tool with routing, refusal modes, and cost implications, the description covers all essential aspects: what it does, how it behaves, exactly what it returns (including refusal reasons), when to use it, and when to prefer an alternative. Since there is no output schema, the detailed return format in the description fully compensates. Sibling tools like ask_pipeworx and validate_claim are also contextually addressed.

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

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

All six parameters are aliases for 'question' and the schema descriptions cover them 100% (e.g., 'Alias for question'). The description adds no new parameter-level semantics beyond stating that the tool 'fills arguments' internally, which is not tied directly to this tool's input parameters. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode that routes through tools and extracts answers only from tool results. It explicitly distinguishes itself from ask_pipeworx by mentioning the same routing but with added extraction and refusal logic, and it includes the exact return shape. This is a specific verb+resource with strong sibling differentiation.

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 like financial verdicts. It also states when NOT to use it: 'prefer ask_pipeworx for casual lookups', and names the alternative directly. The cost trade-off (one extra LLM call) further informs the decision.

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

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

The description extensively details behaviors beyond annotations: market resolution, classification, fan-out, evidence packet, resolver contract, parent event extraction, news fields with fallback handling, safety checks for low-confidence matches, closed market handling, wide-spread warnings, and resolution-rule risk. Annotations already declare read-only, idempotent, non-destructive, and the description adds substantial operational context without contradiction.

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

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

The description is very long and dense with examples and edge cases. While the first sentence is clear, the overall structure is not concise. It contains comprehensive information but could be better organized for quick consumption.

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

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

Given the tool's complexity (multiple input formats, numerous data sources, resolver contract, parent event extraction, safety mechanisms) and absence of an output schema, the description is remarkably thorough. It covers all major behaviors, edge cases, and return shapes, ensuring an agent can fully understand the tool's operation.

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

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

The input schema has 100% description coverage, so the schema already defines parameters adequately. The description does not add new semantic information beyond what is in the schema properties. It provides usage examples but no deeper parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and provides usage examples. It effectively distinguishes from sibling tools like polymarket_arbitrage by focusing on gathering evidence for decision-making.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not provide explicit alternatives or when not to use it. The context is clear, but exclusion guidance is missing.

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

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

Annotations already indicate safe, non-destructive behavior. The description adds valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and result sorting by primary metric. No contradiction with annotations.

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

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

The description is informative and front-loaded with trigger phrases. It is slightly verbose but every sentence adds value, covering triggers, usage, data sources, and output. Could be trimmed slightly without losing substance.

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 two entity types and no output schema, the description is complete. It covers inputs, data sources, edge cases (fiscal year handling), result ordering, and output format (paired data + citation URIs). No gaps.

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

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

Schema coverage is 100%. The description adds meaning beyond the schema: explains what data each entity type retrieves (e.g., revenue, net income for companies; adverse events for drugs), and gives examples. Parameter details are thorough.

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: side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides natural language triggers and distinguishes itself from siblings by explicitly preferring over sequential lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It gives clear guidance on when to use (comparison queries) and implies when not to use (single entity lookups).

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

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

Annotations already mark this as read-only and idempotent, but the description adds valuable behavioral context: it probes live upstream sources at call time, lag varies between calls, and it never reports an unobserved lag. It also notes the _blsKey parameter's effect on rate limits, going beyond the schema.

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

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

The description is longer than ideal but front-loaded with the core purpose. Every sentence adds useful information, though the many parenthetical examples could be tightened. It remains well-organized and 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?

For a read-only probe tool with no output schema, the description covers the key aspects: what it measures, which sources are covered, how to scope it, and the live-probing behavior. It lacks an exact return format, but the description's mention of 'reports the observed lag' is sufficient 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?

Schema coverage is 100%, but the description enhances parameter understanding by explaining the forgiving match for `source`, giving concrete examples, and clarifying that omitting parameters probes everything. This adds semantic value beyond the schema's basic type and 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 measures publication lag for a curated set of live-data sources, using a specific verb+resource structure. It also distinguishes itself by emphasizing live probing rather than reading a hardcoded table, which sets it apart from sibling tools.

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

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

The description provides clear context for when to use it (e.g., 'Use before pricing or settling off a number') and gives concrete example queries. It does not explicitly mention when not to use it or name alternatives, but the context is strong enough to guide an agent.

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 readOnly/openWorld/idempotent, the description goes far beyond: it discloses account requirements and paid plan, explains the findings packet structure (evidence, confidence, gaps[], contradictions[]), citation resolvability rules, semantic excerpting, hop behavior, and latency. It adds deep behavioral context without contradicting annotations.

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

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

The description is long but each sentence earns its place given the tool's complexity. It is front-loaded with the critical account gate and alternative tool, then progresses through usage, output, and edge cases. Slight deduction for density that could make quick scanning harder, but structure is logical and non-redundant.

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

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

With no output schema, the description carries the full burden of explaining return values. It comprehensively describes the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, and citation_uri semantics, plus latency expectations. An agent is fully equipped to invoke and interpret results without guessing.

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 detail beyond the schema: it explains the second-hop iteration behavior (standard re-angles gaps, thorough chases leads), indicates thorough requires a paid plan, and provides example question shapes. This elevates the score to 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 states a specific verb+resource: "grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources" in one call, clearly differentiating itself from open-web search. It also distinguishes from siblings by noting it is NOT open-web search and contrasting with ask_pipeworx for single lookups. The purpose is unmistakable.

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

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

The description provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, with examples like "compare X and Y's regulatory + financial exposure". It also specifies exclusions: use ask_pipeworx for single lookups, breaking/current news, and when not signed in. This is exemplary 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the description adds value by describing the return format (top-N tools with schemas) and readiness to call. 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 paragraphs with no fluff. Front-loaded purpose, each sentence adds value: purpose, domains, return format, usage guidance.

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

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

Given 6 parameters and no output schema, the description covers purpose, usage, return structure. Lacks details on matching logic but overall sufficient for a discovery tool with good annotations.

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

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

Schema coverage is 100%, but the description adds context with examples and mentions alias parameters. This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool finds tools by describing data or task, using specific verbs like 'find' and 'discover'. It distinguishes from siblings by positioning itself as the first call to see available tools, unlike other search tools that search within data.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set'. Lists many domains, implying when to use. Does not exclude alternatives but gives clear context.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it fans out across multiple sources in parallel, returns specific data fields with ordering, uses fallback logic (GDELT→GNews), and handles patent sunset gracefully (soft-fail). 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 comprehensive but somewhat lengthy. It front-loads example queries and provides a clear imperative directive. Every sentence adds value, though minor restructuring could improve scanability.

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 fully explains return fields (CIK, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), ordering, limits, and fallback behavior. Sufficient for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% with both parameters described. The description reinforces that type must be 'company' and value accepts ticker or zero-padded CIK, and adds critical guidance: names not supported and to use resolve_entity instead. This adds value beyond schema.

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

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

The description clearly states it provides a full cross-source profile for US public companies in one parallel call. It lists multiple example user intents ('tell me about X', 'research Acme', 'brief me on Tesla') and differentiates itself from siblings like compare_entities and resolve_entity.

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

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

Explicitly states to prefer this over chaining single-pack lookups for holistic views. Tells users when not to use it (if only have a name, use resolve_entity first) and notes patent data may be unavailable after May 2025.

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 states 'delete', aligning with annotations destructiveHint=true and readOnlyHint=false. It adds context about clearing sensitive data, enhancing 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 concise with two sentences: the first states the core action, the second provides usage guidance. No wasted words.

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

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

Given the tool's simplicity (one required parameter, no output schema) and comprehensive annotations, the description fully covers purpose, usage, and behavior. No gaps.

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

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

Schema coverage is 100%, and the description does not add significant meaning beyond the schema's 'Memory key to delete'. Baseline 3 is appropriate as the schema already covers the parameter well.

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 'Delete a previously stored memory by key', which provides a clear verb and resource. It is distinct from sibling tools like '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 specific situations for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with related tools. Missing explicit when-not-to-use, but sufficient for context.

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

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

The description adds behavioral context beyond annotations: it fetches the page, extracts title/description/key links, and emits standard markdown format. Annotations already indicate readOnly, idempotent, non-destructive, and open world. No contradiction.

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

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

The description is concise, front-loading the main purpose in the first sentence, followed by a brief behavioral summary and a list of use cases. It is efficiently structured with minimal 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?

Given the simple tool with 2 parameters and no output schema, the description adequately covers what the tool does, its output format (text blob), and its use cases. It lacks limitations or error handling but is sufficient for a read-only, idempotent 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 describes both parameters. The description mentions 'for any URL' and 'Maximum number of link entries' but adds no additional semantic detail beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the context for AI crawlers. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than analysis.

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

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

The description explicitly lists three use cases: indexing a client's site, drafting for own projects, and auditing competitor AI visibility. This provides clear when-to-use guidance, though it doesn't explicitly state when not to 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that it returns 'connection details and gateway URLs', which is minor behavioral context. No contradiction with annotations.

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

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

Two concise sentences, no fluff, front-loaded with the key action and result. 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?

Given the tool's simplicity (one parameter, output schema present, annotations rich), the description fully covers its purpose and use. No need for more detail.

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

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

Schema covers the single parameter 'slugs' with a complete description including examples. Description does not add any additional parameter-specific meaning, so baseline 3 applies.

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

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

Description clearly states 'Get MCP setup instructions for connecting to Pipeworx packs' with specific verb 'Get' and resource 'connection config'. It distinguishes from sibling tools like search_packs or list_packs by focusing on setup instructions.

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

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

Explicitly says 'Use to configure your environment', providing clear context for when to use. However, does not mention when not to use or name alternative tools, but given its simple nature, this is acceptable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool is known to be safe. Description adds value by stating it returns 'tool names, descriptions, parameters, and requirements', providing 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?

Two concise sentences: first states purpose, second provides usage guidance. No wasted words.

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

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

Given the tool has an output schema and only one parameter, the description adequately explains its purpose, usage, and return content. No gaps.

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

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

Schema coverage is 100% with a well-described slug parameter. The description adds examples ('weather', 'stocks') but adds no new semantic meaning beyond what the schema already provides.

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

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

Description uses specific verb 'Get' and resource 'tool definitions for a specific pack', clearly distinguishing from sibling tools like list_packs (which lists packs) and search_packs (which searches packs).

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?

Description explicitly says 'Use before calling a tool to verify its interface', providing clear context for when to use. However, it does not exclude when not to use or mention 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 mark as read-only and idempotent. The description adds value by specifying the exact output fields (pack count, active tool count, service alerts), providing context beyond the structured hints.

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

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

Two concise sentences: first states purpose, second describes outputs and usage. No redundant or irrelevant information. Efficient and front-loaded.

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

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

Given an output schema exists, the description does not need to detail return structure. It covers key outputs and usage context, sufficient for a simple health check 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?

No parameters exist, so the description correctly omits parameter details. Schema coverage is 100% trivially, baseline for no params is 4.

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

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

The description clearly states the tool checks platform health and availability, listing specific return values (pack count, active tool count, service alerts). It distinguishes from sibling tools like data_freshness or recent_alerts by focusing on overall platform status.

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

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

The description explicitly says 'Use to verify system status before operations,' providing a clear usage context. It does not list exclusions or alternatives, but the purpose is specific enough that alternatives are not critical.

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?

Given annotations already declare readOnlyHint=true and destructiveHint=false, the description adds behavioral value by disclosing the return fields (pack names, categories, tool counts, gateway URLs) and the exploratory use case. It does not describe any limitations (e.g., pagination) but the provided annotations and return-field disclosure are sufficient context. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the main action and purpose, followed by a concise usage note. Every sentence provides value 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?

For a simple listing tool with one optional parameter and an output schema, the description covers the main purpose, return contents, and usage intent. The schema fills in the parameter details. It is not overly verbose but sufficient for an agent to understand the tool's scope. It could have hinted at the optional category filtering in the description, but the schema covers this, so completeness is high.

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 optional 'category' parameter, with a detailed description explaining it is a free-text filter and not a fixed taxonomy. The description itself does not mention this parameter, but because the schema fully documents it, 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 uses a specific verb ('Browse') and resource ('Pipeworx packs'), and further specifies the return contents (pack names, categories, tool counts, gateway URLs). The phrase 'all available' distinguishes it from sibling tools like search_packs, which implies a search-oriented alternative.

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 states when to use the tool ('Use to discover data sources or explore what's available'), providing suitable context. It does not explicitly mention exclusions or alternatives, but the 'all available' wording implies a browse-all scenario, making it distinct from search tools. This is clear context but lacks explicit when-not guidance.

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

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

Annotations (readOnlyHint, destructiveHint, etc.) already convey safety traits. The description adds value by specifying the caller's scope ('your') and listing return fields, which helps set expectations beyond the structured metadata.

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

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

Two sentences, zero waste. The main purpose appears first, and the second sentence provides actionable guidance. Every clause earns its place.

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

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

For a simple list tool with one optional parameter, the description provides return fields and usage guidance. No output schema exists, but the stated return fields suffice. No gaps remain.

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

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

Schema coverage is 100% for the single parameter (include_inactive), and the description does not elaborate beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('List') and resource ('the caller's active subscriptions'), and specifies the returned fields (id, type, params, etc.), leaving no ambiguity about the tool's purpose and scope.

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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke this tool, though it does not mention when not to use it or name 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 are all false/neutral, so the description carries the burden. It discloses meaningful behaviors: filing returns a claim_token, the token can be used later to poll status ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), rate-limit is '5 per identifier per day,' and it's free. It doesn't explicitly state persistence or side effects, but the token workflow and rate limit provide substantial 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 longer than average, but every sentence serves a distinct purpose: purpose, trigger conditions, exclusion, token workflow, rate limit, and cost. It is front-loaded and well-organized, though slightly dense; a bit more whitespace or shorter sentences would improve scannability, but the length is justified by the tool's complexity.

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

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

For a feedback tool with no output schema, the description explains the full call cycle: what to send, what to expect (claim_token), how to later retrieve the result, and operational details (daily digest, rate limit, quota). It also covers the 'not sure' case by tying names to the connection's listing. No significant gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by giving usage syntax for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) with no other arguments') and instructing users on message content ('don't paste the end-user's prompt'), which enriches the schema's raw parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools by scoping it to tools served by this Pipeworx connection and explicitly excluding tools from other MCP servers, unlike ask_pipeworx or discover_tools.

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

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

Explicitly states when to use: '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 a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' plus a disambiguation rule based on connection listing.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds value by explaining data sourcing (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h window-dependent). No contradiction with annotations.

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

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

The description is two paragraphs with the core statement first, followed by use cases and technical details. Every sentence adds value, with no redundant fluff. Slightly verbose in the use case list but still concise overall.

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

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

Without an output schema, the description sufficiently explains the return format (top tools, packs, total call volume) and adds caching and privacy context. For a read-only trend tool, this covers all necessary information for an agent to understand behavior.

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

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

The schema declares a single optional enum parameter `window` with 100% coverage. The description enriches this by explaining how window length affects results (short windows for hot trends, long for steady-state) and stating the default (24h), going beyond schema semantics.

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

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

The description clearly states that the tool returns top tools, packs, and call volume over a recent window, with specific time options. This is a specific verb+resource combination that distinguishes it from sibling tools by focusing on trending data rather than direct queries or data retrieval.

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 enumerates three concrete use cases: discovering hot data sources, confirming canonical tools, and seeing alignment with agent needs. While it doesn't explicitly state when not to use, the use cases provide clear context for appropriate invocation, and the sibling tools offer alternatives for other purposes.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds extensive behavioral context: monotonicity checks, partition filter (placeholder exclusion), fill check against CLOB depth, and semantic anchor (Jaccard similarity). No contradictions.

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

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

The description is detailed and well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) but is somewhat lengthy. Despite this, it is front-loaded with the core purpose and uses clear formatting to aid readability.

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

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

Given the tool's complexity (multiple modes, arbitrage detection logic), the description is thorough. It explains the output format (opportunities[], partition_check), the fill risk mechanism, and conditions to avoid trading, leaving no critical gaps despite the lack of an output schema.

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

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

Schema coverage is 100%, but the description greatly enriches parameter meaning. It explains the difference between event and topic modes, provides example inputs for each, and details the internal logic (partition_check, fill checking) that each parameter triggers.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing its specific approach and modes.

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

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

Explicitly explains when to use each parameter: no args for trending_scan, event for single-event, topic for cross-event. Provides real-world examples and warns when not to execute a trade (e.g., realizable_edge_pp ≤ 0).

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 extensive behavioral context: caching at KV level keyed on knobs, diagnostics for empty segments, edge calculation details, and tradeable-edge filters. No contradiction with annotations.

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

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

The description is very detailed but overly verbose; while it has clear structure with sections, it could be more concise. The key information is front-loaded, but the length may hinder quick parsing by an AI agent.

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

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

Given the complexity (9 parameters, multiple segments, no output schema), the description covers response structure, edge calculation, filtering, caching, and diagnostics extensively. It provides complete guidance for an agent to use the tool correctly.

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

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

All 9 parameters are described in the schema (100% coverage), but the description adds further value by explaining the rationale and examples for key parameters like slippage_pp and min_partition_leg_kelly, going 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 clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today' use case. It distinguishes from siblings by naming three model families and segments, making it unique among similar tools.

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

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

The description explicitly states it's built for discovering opportunities without paging, and provides guidance on tradeable-edge knobs like min_liquidity and max_spread_pp. However, it does not explicitly mention when not to use it or directly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_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?

The description goes well beyond annotations by detailing response structure (tracked[], expired[], snapshot_dates[]), field meanings (trend, decay_pp_per_day), limitations (60-day TTL, intraday vs daily closes), and data gaps. No contradiction with annotations.

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

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

The description is dense but well-organized: starts with a clear purpose, lists arguments concisely, then details response in capital letters, and ends with limits. Every sentence earns its place with no 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?

Despite no output schema, the description fully explains the complex return structure and interpretation of fields like trend and decay_pp_per_day. It also covers limitations and data-gap reasons, making the tool fully understandable 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 baseline is 3. The description adds operational context beyond schema: default values, maximum lookback, and the role of 'window' in selecting snapshot families. This helps the agent understand parameter impact.

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: 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical snapshots and decay analysis.

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 on when to use this tool—e.g., differentiating a fresh wide edge from an old one—but does not explicitly list when not to use it or name alternative tools. The implicit contrast with polymarket_edges serves as a guide.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains that the tool walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and describes the basket mode's forced directional risk. There is no contradiction with annotations.

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

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

The description is well-structured with clear sections for requirements, single-market mode, basket mode, and usage guidance. While it is somewhat lengthy, every sentence conveys essential information, and the content justifies the length. Minor improvement could be made by further condensing some phrases.

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

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

The tool is complex with two modes and multiple return fields. The description lists all returned fields and explains their meaning. Since there is no output schema, the description compensates well. However, it could mention edge cases like insufficient order book depth, but overall it is complete for the intended use.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the side parameter's default behavior for basket mode, the interpretation of size_usd (max spend on buys, target proceeds on sells, clamp 10-1,000,000), and the distinction between market and event parameters. This additional context justifies a score above 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 purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly mentions it should be used before acting on arbitrage signals, making the purpose specific and unambiguous.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the risk of partial fills converting an arb into an unhedged directional position, effectively telling the agent when to use the tool and why.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description details behavioral traits: it explains the safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) and conditions under which the tool reports no arb exists or events are unrelated. There is no contradiction with annotations.

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

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

The description is long but efficient, with every sentence adding value. It is front-loaded with the core purpose and modes. Minor improvement could be using bullet points for modes, but overall it is well-structured and not 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 zero output schema and three optional params, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and covers edge cases (non-equivalent bet shapes, temporal misalignment). It is complete for a read-only cross-venue spread 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%, providing a baseline of 3. The description adds significant value by explaining the purpose of the topic parameter (10 pre-mapped shortcuts listed explicitly) and how explicit tickers override the topic-mapped side. Examples further clarify usage.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes and indicates it distinguishes between equivalent and non-equivalent bet shapes, setting it apart from siblings like polymarket_arbitrage and bet_research.

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

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

The description provides explicit guidance on when to use the tool (comparing the same outcome across venues), lists the pre-mapped macro shortcuts, explains how to use explicit event tickers, and advises when spreads are not meaningful via compatibility_warning and temporal_alignment fields. It even notes that pre-mapped topics may not always be tradeable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: scoping to user identifier, listing all keys when key omitted, and examples of stored data. No contradiction with annotations.

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

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

Two sentences, no wasted words. Front-loaded with the core action, then provides context and pairing. Highly efficient.

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

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

For a simple read tool with one optional parameter and good annotations, the description covers usage, scoping, and pairing. No output schema, but return values are implied. Minor gap: no explicit mention of what happens if key not found (returns null/error).

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

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

Schema coverage is 100% with one optional key parameter. Description explains the effect of omitting the key (list all keys) and the purpose of the parameter, adding meaning beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys, with specific examples of use cases (ticker, address, research notes). It distinguishes from sibling tools 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?

Explicitly states when to use (look up stored context) and pairs with remember/forget. Mentions scoping by identifier. Could be improved by clarifying when not to use, but it's sufficient.

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 readOnlyHint, idempotent, non-destructive. Description adds behavioral detail: mark_read side effect that flags events read, affecting future calls. 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?

Four sentences that efficiently cover purpose, returned fields, filtering, and alternative access. Slightly verbose but front-loaded with key info.

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?

No output schema, but description explains return fields. Covers essential aspects for a list tool with good annotations. Could mention pagination but limit parameter is in 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%, baseline 3. Description adds example filter values for type and clarifies mark_read behavior, providing meaningful context beyond schema.

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

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

Clearly states it pulls fired events from subscription feed and lists returned fields. No explicit differentiation from sibling tools like 'recall' or 'recent_changes', but the scope is specific and distinct.

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?

Mentions polling and an alternative HTTP endpoint, but does not provide guidance on when to use vs. other tools or when not to use. Lacks explicit when-to-use and when-not-to-use directives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds rich context: parallel API fan-out, fallback mechanisms (GDELT→GNews), soft-failure for patents, and output format (changes grouped by source with URIs). No contradictions.

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

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

Four sentences that front-load purpose, then cover inputs, sources, output, and sibling distinction. No fluff; each sentence adds essential information. Very efficient.

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

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

Even without an output schema, the description fully covers inputs (type, since, value), sources (SEC, GDELT/GNews, USPTO), output structure (grouped changes, total count, URIs), and a cross-reference to entity_profile. Agent has enough context 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%, but the description adds crucial meaning: explains `since` formats (ISO date or relative shorthand like '7d'), example values, and supports for ticker or CIK. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose as a change feed for a company within a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishing it from sibling entity_profile. The introductory query examples further clarify intent.

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: when to use this tool vs. entity_profile, explains query patterns (e.g., 'latest on Y'), and details fallback logic (GDELT preferred, GNews on failure). This fully informs agent decision-making.

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

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

Discloses key-value pair storage scoped by identifier, persistent vs 24-hour retention based on auth, and pairing with recall/forget. Annotations already indicate idempotent and non-destructive, so description adds valuable context without contradiction.

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

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

Concise at ~70 words, front-loaded with main purpose, then usage, then storage details. No unnecessary sentences.

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

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

Covers purpose, usage, behavioral details, and sibling relations. No output schema, but tool is simple enough that return behavior is implied. Complete for a storage tool.

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

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

Schema coverage is 100% with clear descriptions. The description adds example keys but no further semantic detail beyond schema. Baseline 3 is appropriate as description doesn't significantly enhance parameter meaning.

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

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

Clearly states the tool saves data for later reuse, provides concrete examples (resolved ticker, target address), and distinguishes from siblings by mentioning recall 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?

Explicitly says 'Use when you discover something worth carrying forward' and lists common use cases. Implicitly clarifies when not to use, but lacks explicit when-not guidance.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses valuable behavioral details: identifiers are labeled with their source, unresolved identifiers are explicitly listed under `unresolved`, and enrichment degrades gracefully if GLEIF or OpenFIGI are unavailable. This provides deep context and is consistent with the read-only, idempotent nature.

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 prominent sections like "USE FIRST" and "SUPPORTED TYPES." The opening list of example queries is somewhat repetitive, but the structure keeps the entry points clear and each part 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?

Despite having no output schema, the description thoroughly covers return semantics (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand), source labeling, unresolved handling, and graceful degradation. This makes it complete enough for an agent to understand how the tool behaves across different scenarios.

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 context by explaining accepted input forms for each type (ticker, CIK, or name for company; brand/generic for drug) and describing what identifiers each type returns, going beyond the terse schema descriptions.

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

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

The description clearly states the tool's function: resolving a user-spoken name to canonical/official identifiers such as CIK, ticker, LEI, and RxCUI. It uses specific verbs and examples ("What's the ticker for...") and distinguishes itself from sibling tools by positioning it as the first step for ID lookup.

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

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

It gives an explicit directive: "Use FIRST whenever you have a name but need an ID." This clearly indicates when to use it, but it does not explicitly mention when not to use it or name alternative tools, so while context is clear, exclusions are missing.

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

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

Annotations already declare safe, idempotent, read-only behavior. Description adds that it probes each entity with ai_visibility_check and returns ranked list with score, confidence, signal density. 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, front-loaded with purpose and outcome. No wasted words. Efficient and clear.

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

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

Despite no output schema, description details the return (ranked list with score, confidence, signal density). Annotations cover behavior, parameters are documented in schema, and description fills the gap for 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 covers 100% of parameters with descriptions. Description adds value by explaining that the first entity is treated as subject and context disambiguates common names, beyond what schema provides.

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

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

Description uses specific verbs ('Compare', 'probes', 'ranks', 'surfaces') and clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic). States the resource: AI visibility across multiple entities.

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

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

Gives a concrete use case ('competitive AI-marketing audits') and a direct question it answers ('does Claude know about us as well as our competitors?'). Lacks explicit when-not-to-use or alternatives, but context 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral detail about partial failures: bundlephobia's first measurement can take 5-30s, and sources_failed will list it if it times out. This goes beyond annotations but does not describe the full retry or caching 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 relatively long but every sentence adds value. It is front-loaded with the main purpose. Minor redundancy: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly' could be slightly tightened, but overall good 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 no output schema, the description comprehensively lists return fields: summary block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and recent alternative versions. It also covers edge cases like partial failures and timeouts. Complete for a read-only composite tool.

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

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

Schema coverage is 100%, but description adds meaning: it clarifies that scoped packages (e.g. '@types/node') are accepted for the 'package' parameter, and explains that 'version' defaults to the latest published version when omitted. This adds practical 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 it is a composite 'should I add this npm package' check combining deps.dev and bundlephobia. It specifies the verb ('scan'), resource ('dependency'), and outcome (license, advisories, bundle size). It distinguishes from sibling tools by explicitly scoping to npm packages only, with mention of NPM ecosystem.

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 an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states what it does NOT cover (PyPI, Maven, etc.) and gives fallback guidance (use deps.dev:version directly for others). This provides clear when-to-use and when-to-avoid context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat those. It adds that the tool searches a directory of thousands of MCP servers and returns community and hosted servers, which is relevant behavioral context without contradiction.

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

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

Two sentences, each delivering core information: what the tool does and when to use it. No extraneous words, front-loaded with the action, and examples are embedded efficiently.

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

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

Given the output schema exists, return values are handled. The description covers purpose, scope, and usage context thoroughly, with high schema coverage and clear annotations. Nothing additional is needed for an agent to understand how and when to 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by providing example values for the query parameter and clarifying it is by use case, enhancing understanding beyond the schema's basic descriptions.

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

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

The description clearly states the tool searches MCP servers by use case, with examples like 'database', 'email', 'calendar'. It distinguishes itself from siblings by noting it returns servers beyond Pipeworx, avoiding confusion with internal search tools like search_packs.

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 specifies to use this tool when looking for tools beyond Pipeworx, providing clear context. While it doesn't explicitly list when not to use, the phrase 'beyond Pipeworx' implies it is for external servers, and sibling names suggest alternatives like search_packs are for internal tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that it searches across specific fields (names, descriptions, tools) and returns details, which is useful but not extensive. 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 front-load the core action and usage. Every sentence adds value with no redundancy. Perfectly concise for the tool's simplicity.

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

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

Given the single parameter with full schema coverage, rich annotations, and an output schema, the description provides sufficient context. It could mention pagination or result format but output schema fills that gap. Slightly above baseline.

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 single 'query' parameter described as 'Search query'. The description adds 'by keyword' but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action 'Search packs by keyword' and specifies the scope 'across names, descriptions, and tools'. It provides concrete examples ('weather', 'translate') and explains the return value. This distinguishes it from siblings like 'list_packs' which lists all packs.

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 tells when to use it: 'Use to find specific capabilities.' While it doesn't explicitly mention when not to use it or compare with alternatives, the context of sibling tools like 'list_packs' and 'get_pack_tools' implies different use cases. A brief exclusion statement would improve 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?

Adds significant detail beyond annotations: embedding model (BGE-base-en), chunking (500-char overlapping windows), char cap (200K with truncation), output includes offsets. Annotations already declare read-only, idempotent, non-destructive; description enriches understanding.

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?

Single paragraph is front-loaded with core action, then usage case, then pairing, then technical details. Every sentence adds value; no fluff.

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

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

Even without output schema, description states return format (passages with offsets and scores). All parameters are explained. Annotations cover safety. Complete for a focused search 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 baseline 3. Description adds value by providing query examples and reinforcing the text max. It explains limit's purpose (max passages) and natural-language query style.

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: 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). It distinguishes from siblings by mentioning its pairing with ask_pipeworx_grounded and implying it is for large records.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Lacks explicit when-not-to-use guidance but 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?

Discloses important behaviors beyond annotations: returns subscription ID, requires OAuth, delivery channels include always-on feed, SMS has 10/day cap, webhook secret returned once and auto-disabled after 10 failures. No contradiction with annotations (all consistent).

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?

Well-structured with key information front-loaded (purpose, types, delivery). Some redundancy in the delivery section (phone verification mentioned twice) but overall each sentence adds value. Could be slightly more concise.

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 subscription types, nested parameters, delivery channels), the description is comprehensive. Covers prerequisites, rate limits, return value, and behavior of each channel. No output schema, but the described return is sufficient.

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

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

Schema coverage is 100% and the description adds detailed semantics: type enum with use-case examples, params object with type-specific structures (e.g., items codes for sec_8k, topic for polymarket_edge), delivery object with validation requirements. Provides far more meaning than the schema alone.

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

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

Clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. Describes supported types and delivery channels, distinguishing it from related sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

Explicitly mentions prerequisites (Pipeworx OAuth account, phone verification for SMS) and provides type-specific parameter examples. However, it does not explicitly contrast with alternatives or state when not to 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it returns category-bucketed example questions with tool+argument shapes, and explains its role as a discovery entry point. No contradiction with annotations.

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

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

Description is comprehensive but slightly longer than necessary. However, every sentence adds value, and the structure is logical with clear sections. Close to a 5, but minor redundancy in listing examples.

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 purpose as a discovery/onboarding tool with no output schema, the description fully explains its return value (category-bucketed questions) and usage scenarios. Leaves no significant gaps.

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

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

Schema coverage is 100% for the single optional parameter 'topic'. Description adds meaning by listing possible values (finance, pharma, etc.) and stating omission yields a cross-category spread, which goes beyond the schema's 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 as the onboarding entry point for suggesting questions, using specific verbs like 'get ideas', 'show examples', and identifies the resource ('Pipeworx'). It distinguishes well from siblings like 'ask_pipeworx' and 'discover_tools'.

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

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

Explicit guidance to use this tool first when unfamiliar with Pipeworx or to learn meta-tools. Provides context for optional topic parameter (use to focus or omit for full spread). No explicit when-not, but 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 goes beyond annotations by stating that the row is deactivated (not deleted) and that historical events remain available via 'recent_alerts', adding valuable behavioral context not captured by annotations.

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

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

Three sentences, each necessary and informative, no filler. Information is front-loaded with the core action.

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 mutation with one parameter and no output schema, the description fully covers the tool's effect (deactivation), constraint (ownership), and relation to other tools (recent_alerts).

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 no extra parameter information beyond what the schema already provides ('Subscription id (uuid) returned by subscribe').

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 verb 'Cancel' and the resource 'subscription by id', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly notes ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, providing clear context for when to use this tool, though it doesn't name alternative tools for similar tasks.

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

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

The description goes beyond annotations by explaining the verdict taxonomy, especially the critical distinction between could_not_verify (verification did not happen) and unsupported (no source found), and warns not to treat could_not_verify as evidence. It also discloses the structured vs grounded pipeline and the error detail structure.

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 each section serves a purpose: query patterns, usage, pipeline behavior, and error semantics. It is front-loaded with examples and structured such that an agent can parse key information efficiently.

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

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

With no output schema, the description compensates by specifying the return verdicts, the actual value with citation, and reasoning, plus the meaning of error states. It gives enough context about the dual-path routing and the replacement of multiple calls to make the tool fully actionable.

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

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

The input schema already provides full descriptions for both parameters, including examples and tolerance semantics. The description adds no new parameter-level details, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with explicit query examples and the verb 'verify'. It distinguishes from siblings by describing the dual path (SEC EDGAR/XBRL for company-financial, grounded pipeline for other claims) and notes it replaces 4–6 sequential calls.

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

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

It states 'Use whenever the agent needs to check whether something a user said is factually correct', giving an explicit trigger condition. It further distinguishes the two claim categories and explains the fallback behavior, effectively covering all factual claims without ambiguity.

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