Kegg

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

Description reveals that the tool probes multiple models, uses a default free model, requires a BYO key for Anthropic, and returns per-model scores plus combined view. Annotations (readOnlyHint, openWorldHint, idempotentHint) are already present, but the description adds significant operational detail beyond them, such as scoring mechanism and API key handling.

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

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

Three sentences with no waste. First sentence states purpose and output, second gives model and key details, third lists use cases. Front-loaded with key information.

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

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

No output schema exists, but description explains return format (per-model fields + combined view). All parameters are explained in schema and description. Use cases and limitations (e.g., key requirement for one model) are covered. Complete for this complexity level.

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 4 parameters are documented in schema (100% coverage). Description adds extra context: default model name for 'models' parameter, that _apiKey is passed through to Anthropic, and that 'context' helps disambiguate. This provides meaning beyond schema descriptions.

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

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

Description clearly states the tool probes LLMs for brand visibility and scores it, with specific verb 'Probe' and resource 'LLMs'. It distinguishes from siblings like ask_pipeworx and scan_competitor_ai_presence by focusing on visibility scoring rather than general Q&A or competitive scanning.

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 lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also provides guidance on default model and when to use _apiKey. Lacks explicit when-not-to-use, but context is clear enough for selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: the tool routes questions to one of 3,745 tools, returns structured answers with stable citation URIs. This goes beyond the annotations in explaining the mechanism and output quality.

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 one focused paragraph, front-loaded with the key instruction to prefer over web search. It efficiently conveys usage scope, examples, and output characteristics. A bit lengthy but each sentence adds value; 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?

Given the tool's high complexity (routing to many tools, no output schema), the description is remarkably complete. It covers when to use, how it works, input types, and provides concrete examples. No missing essential information for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100% with all parameters having descriptions. The description adds no new meaning beyond reiterating that the parameter is a natural language question. The schema examples provide concrete usage, but the description does not enhance understanding of the parameter.

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

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

The description clearly states the tool's purpose: to answer factual questions about current/historical data using authoritative structured data with citations. It explicitly distinguishes from web search and lists many specific domains (SEC filings, FDA drugs, etc.), making the purpose highly specific and distinct 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 strong guidance on when to use this tool over alternatives, explicitly stating 'PREFER OVER WEB SEARCH' and listing question types like 'what is', 'look up', 'find', etc. It gives examples but does not explicitly mention when not to use it or alternative tools, though sibling tools exist.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds concrete refusal modes, return structure, and the exact extraction process 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?

Concise single paragraph front-loaded with purpose, followed by behavior details, usage guidance, and cost trade-off. Every sentence adds value 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?

Complex tool (3745 tools, 884 sources) with no output schema, but description fully specifies return structure (answer, evidence, confidence, source, etc.) and refusal scenarios. Covers cost, routing, and extraction 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?

Schema coverage is 100% with all parameters documented as aliases for 'question.' Description adds no new meaning beyond listing aliases already present in the schema. Baseline 3 for high coverage.

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

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

Description clearly states 'Hallucination-resistant answer mode for high-stakes reads' with specific verb 'extracts the answer using ONLY what the tool result contains.' Distinguishes from sibling ask_pipeworx by noting the grounded extraction and refusal reasons.

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 advises use when answers will be quoted/cited/acted on and the agent must not invent facts. Recommends prefering ask_pipeworx for casual lookups, and notes the extra LLM call cost.

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

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

The description discloses extensive behavioral traits beyond annotations, including resolution mechanism, classifier system, fan-out examples, response shapes, resolver contract, parent event extraction, news fallback handling, safety short-circuits for low-confidence matches and closed markets, liquidity warnings, and resolution-rule risk. This provides deep transparency.

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

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

The description is lengthy but front-loads the core purpose and usage. It is comprehensive, covering many details in a single paragraph. While not overly concise, every sentence adds value; however, it could benefit from more structured formatting (e.g., bullet points).

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

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

Despite lacking an output schema, the description fully describes the response structure (market, analysis, evidence, resolver contract, parent event, news fields) and safety behaviors. It compensates for missing output schema with detailed explanations, making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context like examples of market_input but does not significantly enhance understanding of parameters beyond the schema. The depth and include_raw parameters are sufficiently explained 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 explicitly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes from sibling research tools by being Polymarket-specific.

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 guidance on when to use the tool ('Use for...') and provides examples of inputs (slug, URL, question text). It does not explicitly tell when not to use, but the context implies it is for researching Polymarket bets, not general queries.

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

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

The description adds significant behavioral context beyond annotations: it mentions data sources (SEC EDGAR, FAERS), specific financial items, handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. 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 but slightly long. It is front-loaded with common query patterns and every sentence adds value, though could be tightened slightly. Still effective.

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, with 2 required parameters and no output schema, the description fully covers what to expect: metrics per entity type, sorting, and return format (paired data + citations). It is complete.

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

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

Schema already has 100% coverage with descriptions for type enum and values array. Description adds valuable context: for company, values are tickers/CIKs; for drug, names; and explains what data is pulled per type. This enhances understanding beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call, listing specific financial and regulatory metrics for each type. It distinguishes itself from siblings like entity_profile (single entity) and 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?

It explicitly advises to always prefer this tool over sequential single-pack lookups when comparing entities, and provides concrete query patterns such as 'compare X and Y' or 'rank these companies'. This makes the usage context very clear.

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

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

Beyond the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description adds significant behavioral context: it decomposes questions, routes to sub-questions in parallel, extracts grounded answers with citations and confidence scores, returns explicit gaps, never invents facts, and gives expected execution time (15-60s). 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 informative but slightly lengthy; however, every sentence earn its place. It is front-loaded with the core capability and well-structured. Minor trimming could improve conciseness, but it remains clear and effective.

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

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

Given no output schema, the description thoroughly explains the return format (structured findings packet with verbatim evidence, confidence, source, citations, gaps). It covers prerequisites, usage context, alternatives, and timing. The definition is complete for a complex tool.

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

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

Schema covers both parameters at 100%. Description adds meaning: for depth, it explains what each enum value means (quick=3, standard=5, thorough=8 facets) and that thorough requires a paid plan. For question, it clarifies that natural language and broad/multi-part questions are acceptable. This goes beyond the schema.

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

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

The description clearly states it performs grounded multi-source research in a single call, decomposing questions into sub-questions and routing them to many tools. It distinguishes from the sibling tool ask_pipeworx by noting that deep_research is for broad or multi-part questions, while ask_pipeworx is for single 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?

Explicitly states when to use (broad or multi-part questions) and when not to (single lookups should use ask_pipeworx). Also mentions prerequisites (Pipeworx account) and limitations (depth:thorough requires paid plan), providing clear guidance for the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read operation. The description adds significant behavioral detail: it 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This discloses return format and efficiency benefit 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 well-structured with a clear purpose first, followed by a list of domains and return behavior. It is slightly lengthy due to the domain list but every sentence is informative. No wasted words, though could be trimmed slightly without losing meaning.

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

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

Given the tool's complexity as a meta-tool with 6 parameters and no output schema, the description covers all necessary context: what it does, when to use it, what it returns (top-N tools with schemas), and example queries. It provides complete guidance for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% and descriptions already explain each parameter. The description adds value by providing example queries (e.g., 'analyze housing market trends') and clarifying that multiple aliases (task, q, search, description) are accepted, which helps agents understand input flexibility beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous example domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes itself from sibling tools by positioning it as a meta-tool for discovering them, saying 'Call this FIRST.'

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use and implies not to use when specific tool is known.

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?

Description adds details beyond annotations: it fans out across multiple sources, returns specific fields (CIK, filings, fundamentals, patents with soft-fail note, news fallback), and explains limitations (patents sunset May 2025). 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 relatively long but front-loaded with examples and structured logically. Every sentence adds value, though a bit verbose. Minor deduction for length, but still very effective.

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

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

Given the tool's complexity and lack of output schema, the description is thorough: it lists all return components (filings, fundamentals, patents, news, LEI) and explains behavior (parallel call, fallback, soft-fail). Completely adequate for AI agent usage.

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

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

Adds meaning beyond the input schema: explains that only 'company' type is supported, and that value must be a ticker or zero-padded CIK (not names). Reinforces the resolve_entity alternative. Schema coverage is 100%, but description provides critical usage nuance.

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: providing a holistic cross-source profile of a US public company in a single parallel call. It uses specific verbs and resource references (SEC EDGAR, XBRL, USPTO, etc.) and distinguishes itself from chaining individual 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?

Explicitly advises when to use ('ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view') and when not to (names not supported, recommends resolve_entity first). Provides clear context for 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it is keyless and returns IDs with descriptions, but does not discuss rate limits, result size, or pagination. With strong annotations, the description adds modest value.

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

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

The description is two sentences plus 'Keyless', front-loading the purpose and key details. Every sentence adds value with no fluff.

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

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

For a simple search tool with comprehensive annotations and no output schema, the description covers purpose, valid databases, query examples, and return type. It is self-contained and sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with good descriptions. The description reinforces by listing database options and providing example queries (e.g., 'glucose', 'aspirin'), adding practical context beyond the schema without being redundant.

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

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

The description clearly states it searches KEGG by keyword, lists specific databases and example queries, and returns KEGG IDs with descriptions. It effectively distinguishes itself from sibling tools by specifying the KEGG domain.

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

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

The description implies when to use (for KEGG keyword searches) but does not explicitly compare to sibling tools like search_within or get_entry, nor state when not to use it. The phrase 'Keyless' hints at accessibility but lacks direct guidance on 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?

Description aligns with annotations (destructiveHint=true) but adds no extra behavioral context beyond 'delete by key'. Annotations already cover safety profile, so 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?

Two sentences, front-loaded purpose, efficient and 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?

Complete for a simple delete tool with one parameter and annotations; mentions pairing with siblings. Could mention success/failure behavior but not necessary.

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 single parameter 'key' described. Description does not add meaning beyond the schema; baseline 3.

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

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

Clear verb 'Delete', specific resource 'memory', and method 'by key'. Distinguishes 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?

Explicitly states when to use: stale context, task done, or clearing sensitive data. Mentions sibling tools for pairing.

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 that it fetches the page, extracts title/description/key links, and outputs standard markdown format. This enriches the 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?

The description is three sentences: first states the main action and output, second describes the process, third lists use cases. Every sentence is impactful, no fluff, and front-loaded with the most critical information.

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

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

Given the tool's low complexity (2 params, no output schema, no nested objects), the description fully explains what the tool does, how it works, the output format, and appropriate use cases. It is complete for an agent to understand and invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant detail beyond the schema for the two parameters (url and max_links), but it does provide workflow context. No additional parameter information is needed.

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

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

The description clearly states the verb 'generate' and the resource 'llms.txt file for any URL', specifying the output format and AI crawler use case. It distinguishes from sibling tools by its unique purpose.

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

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

The description explicitly lists three specific use cases (client site indexing, personal project drafting, competitor auditing), providing clear guidance on when to employ this tool. It does not explicitly exclude scenarios, but the listed uses cover the main contexts.

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, and non-destructive. The description adds that the tool returns parsed fields plus raw text, lists example fields, and mentions 'Keyless.' 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?

Concise, front-loaded with the main action, includes examples and a sibling reference. Every sentence earns its place.

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

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

Given one parameter, rich annotations, and no output schema, the description is complete: explains what it returns, ID formats, and how to use it.

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

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

Schema coverage is 100%, and the description provides examples and explains ID formats, adding meaning beyond the schema's brief parameter description.

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

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

The description clearly states it fetches a KEGG flat-file entry by ID and returns parsed fields plus raw text. It distinguishes from siblings by referencing 'find' for ID discovery.

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

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

Provides context: 'Use find first to discover IDs.' This suggests when to use this tool (after finding an ID) and implies a sibling tool for discovery. Does not explicitly state when not to use, but adequate.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds critical behavioral details: results capped at 100 with truncated flag, and 'Keyless' indicating no authentication needs beyond the tool invocation.

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 that are front-loaded with the core action and succinctly cover purpose, usage, and important behavioral notes. Every sentence adds value.

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

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

With no output schema, the description adequately explains the return content (id + description) and the truncation behavior. No missing gaps given the tool's simplicity and full annotation coverage.

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 description essentially repeats the schema's parameter description with added examples. No additional semantic information beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states 'List all entries in a KEGG database' with specific verb and resource. Provides examples like 'pathway', 'drug', 'organism', distinguishing it from sibling tools like get_entry.

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 'Useful for enumerating things like KEGG pathways' and mentions result cap at 100. Does not explicitly state when not to use or present alternatives, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the behavioral safety profile is well-covered. The description adds that it returns specific fields and that include_inactive parameter controls inclusion of cancelled subscriptions, but does not add substantial new behavioral insights.

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 exceptionally concise: two sentences that efficiently convey purpose, return fields, and usage advice. Every sentence adds value, and the key information is front-loaded.

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

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

Given the tool's simplicity (one optional parameter, good annotations, no output schema), the description is complete. It explains what the tool does, what it returns, and when to use it. No gaps remain for an AI agent to correctly 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 coverage is 100%, and the schema already describes the only parameter (include_inactive). The tool description does not add any additional meaning for the parameter; it only describes the return fields. Baseline 3 is appropriate as the schema carries the param meaning.

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

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

The description clearly states the verb (list), resource (subscriptions), and scope (caller's active). It also enumerates the returned fields, leaving no ambiguity about the tool's purpose. It distinguishes itself from siblings like subscribe and unsubscribe.

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

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

The description explicitly advises when to use this tool: 'review what you're monitoring before adding more or to find an id to cancel.' This provides practical guidance. It does not explicitly list alternatives or when not to use, but the context is clear enough given the sibling list.

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 rate limits, freeness, no quota impact, and that team reads digests daily. Annotations are all false, so description carries full burden; 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?

Concise 4-sentence structure: purpose, usage scenarios, behavior notes. No wasted words; front-loaded with main 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 3-parameter tool with no output schema, the description covers what constitutes good feedback, how to use types and context, and message formatting. Fully sufficient for correct 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?

Adds meaning beyond schema by explaining how to write feedback (specific, tool-focused, 1-2 sentences). Contextualizes enum values and message constraints. Schema coverage is 100%, but description enriches further.

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

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

The description clearly states the tool's purpose: sending feedback about bugs, missing features, data gaps, or praise to the Pipeworx team. It distinguishes itself from other tools by its specific feedback role.

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

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

Provides explicit guidance on when to use each type (bug, feature, data_gap, praise), and what to avoid (don't paste end-user prompt). Also includes rate limits (5/day) and that it's free without quota impact.

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. Description adds caching behavior (5min-1h), data derivation method, and no PII, providing useful beyond-annotation context.

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?

Front-loaded with main return in first sentence. Two clear paragraphs with no wasted words. 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?

Simple tool with one optional parameter, no output schema. Description explains return structure and caching. Annotations cover safety. 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 covers the single parameter fully (100% coverage). Description adds nuance: shorter windows for hot trends, longer for steady-state. Baseline 3, extra context justifies 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?

Description clearly states the tool returns trending tools, packs, and call volume. Distinguishes from siblings by specifying self-aggregating signal, no PII, and data source (CF analytics-engine).

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). Explains window trade-offs but does not explicitly state when not to use; however, sibling context implies 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 indicate readOnlyHint=true, consistent with description of a read-only analysis tool. Description goes far beyond annotations: details monotonicity checks, Jaccard similarity thresholds, placeholder filtering, fill check against CLOB depth, and response structure. 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?

Description is well-structured with sections (REQUIRES, event mode, topic mode, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loads the requirement. However, it is quite verbose; some details could be more concise. Still earns its length by being informative.

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

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

No output schema, but description explains response structure (opportunities array, partition_check, fill_check) and error/special cases (no args fail, low similarity count, placeholder filtering). Lacks explicit statement of what happens when no opportunities found, but otherwise highly complete for a complex tool.

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

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

Input schema coverage is 100% with clear descriptions. Tool description adds extra value: explains difference between event slug and topic seed question, provides examples, and describes how each parameter affects behavior. Slightly above baseline due to enriched context.

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

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

Description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' with specific verb and resource. It distinguishes two modes (event and topic), and among sibling tools like polymarket_edges or polymarket_fill_risk, this tool uniquely handles arbitrage detection.

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 tells when to use each parameter: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. Warns that calling with no args fails. Mentions alternative tool 'polymarket_fill_risk' for custom sizing, providing clear usage boundaries.

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

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

The description details caching (1h at KV level), response structure (by_segment with three segments, diagnostics), and behavioral traits like edge computation (net of slippage, Kelly capped at 0.25). This adds significant value beyond annotations (readOnly, etc.) with 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 thorough but excessively long and dense, containing detailed formulas and enumeration of model families. While front-loaded with purpose, the sheer volume of information may hinder quick parsing. Could be more concise without losing essential guidance.

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

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

Given the tool's complexity (9 parameters, no output schema), the description fully covers what the tool returns, including top-level response structure, diagnostic fields, and caching behavior. It enables the agent to understand the output without needing an output schema.

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

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

Schema coverage is 100%, but the description adds meaningful extra context for parameters like slippage_pp (explains Polymarket fees) and min_partition_leg_kelly (explains why min_kelly doesn't filter partitions). This goes beyond what the schema provides, earning above baseline 3.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeting a specific use case ('what should I bet on today'). It distinguishes from siblings by focusing on disagreement rather than arbitrage or other patterns.

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 knobs (min_liquidity, max_spread_pp, etc.) and explains how to filter for tradeable edges. It notes Fed bets are excluded from ranking. However, it does not directly compare with siblings like bet_research or polymarket_arbitrage, leaving when-not-to-use less explicit.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral context: response structure (tracked, expired, snapshot_dates), snapshot write-on-cache-miss behavior, data limitations (60-day TTL, decay from daily closes). 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 well-structured with a clear lead sentence, response format, and limitations section. It is dense but not overly verbose; every sentence adds value for understanding the tool.

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

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

Given the absence of an output schema, the description fully details the response structure, limitations, and behavior. It covers all necessary context for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100% for both parameters. The description adds minor contextual details (defaults, max days) but does not significantly extend parameter understanding beyond the schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry from daily polymarket_edges snapshots' and answers a specific question about edge duration and decay. It distinguishes from sibling tools like polymarket_edges by focusing on historical tracking.

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

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

The description implies when to use the tool (e.g., comparing fresh vs old edges) and gives context about snapshot gaps and limits. However, it does not explicitly contrast with sibling tools or provide exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the tool is clearly non-destructive and idempotent. The description adds behavioral context beyond annotations, such as that it walks the order book ladder, returns a verdict (clean/degraded/cannot_fill), and details risks like forced_directional_risk for basket mode. It does not contradict annotations.

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

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

The description is moderately long but highly structured, with clear sections for REQUIRES, SINGLE-MARKET, BASKET, and a warning. The information is dense and necessary for correct usage. It could be slightly more concise, but the structure aids comprehension.

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 4 parameters and no output schema, the description provides a thorough explanation of return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) for single-market and (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk) for basket mode. This fully compensates for 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 description coverage is 100%, meaning all 4 parameters have descriptions. The tool description goes further by explaining the two modes (single-market vs basket) and how parameters like size_usd are interpreted differently: 'max spend on buys, target proceeds on sells' for single-market, and 'settlement notional S (shares per leg)' for basket. It also clarifies default values and the 'auto' logic for side in basket mode.

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

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

The description explicitly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. It clearly differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying the exact pre-trade check it provides.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also warns about partial basket fills converting arb into an unhedged directional position, which is the dominant loss mode in real arb-bot P&L.

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

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

The description discloses key behavioral traits beyond annotations: compatibility_warning conditions, temporal alignment, skipped cross-type/subtype counters. It explains that the tool says when bet shapes are not equivalent, and that spreads may be meaningless if temporal alignment is false. Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent and the description adds substantial context.

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 effectively front-loaded with purpose and modes, then details response fields and safety notes. While it is lengthy, every sentence adds necessary information; a small amount of redundancy could be trimmed, but overall it is well-organized and concise for the 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?

Given the tool's complexity (two venues, multiple modes, safety checks, no output schema), the description covers everything an agent needs: what the tool does, how to invoke it, what the response contains (raw probabilities, spread, compatibility_warning, temporal_alignment, skipped counters), and edge cases. It is complete and self-contained.

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

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

Schema coverage is 100%, but the description adds significant semantic value: explains the 'topic' enum list, the overriding behavior of explicit parameters, and the overall mode logic. The description makes the parameters' interplay clear, which is crucial for correct tool invocation.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from siblings like polymarket_arbitrage (likely single-venue) and compare_entities (general comparison) by focusing on a specific cross-venue spread 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 provides explicit usage guidance: two modes (topic shortcuts vs explicit tickers), and warns that most pre-mapped topics return compatibility warnings and are not tradeable. It also implies when not to use the tool (when events are not equivalent) and suggests alternatives via explicit mode.

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

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

Annotations already declare readOnly and idempotent. Description adds scoping (by identifier), dual behavior (key vs. no key), and pairing with remember/forget, providing comprehensive behavioral context beyond annotations.

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

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

Three sentences, each adding value. Front-loaded with core functionality, then use cases, then scope. Zero wasted words.

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

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

For a simple read-only tool with one param and no output schema, the description covers purpose, usage, scoping, and relationships. Minor missing detail: behavior when key doesn't exist, but that's a negligible gap.

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 'omit to list all keys' which mirrors the schema. No extra syntax or format details are added beyond what's in the schema, meeting the baseline.

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

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

The description clearly states it retrieves a saved value or lists all keys (verb+resource+scope). It distinguishes from sibling tools like remember and forget by explicitly pairing with them.

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 explains when to use it ('look up context stored earlier') and provides examples. It implicitly advises against re-deriving, but does not explicitly list alternatives for 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?

The description describes a behavioral trait (marking events as read) that contradicts the annotation 'readOnlyHint': true. Per the scoring rule, when a description contradicts annotations, the score must be 1.

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

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

The description is concise (4 sentences) and front-loaded with the main purpose. It could be more structured (e.g., bullet points), but every sentence provides useful information without redundancy.

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

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

The description covers the return values (source, citation_uri, raw payload), filtering options, and behavior of mark_read. Without an output schema, it adequately describes expectations. Minor gaps like pagination not mentioned, but overall complete for the tool's complexity.

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

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

The description adds context beyond the schema by giving usage examples for 'type' (e.g., 'sec_8k') and explaining the effect of 'mark_read:true'. Since schema coverage is 100%, baseline is 3, but the additional examples and side-effect explanation justify a 4.

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

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

The description clearly states the tool 'Pull fired events from your subscription feed' and specifies the kind of data returned (source, citation_uri, raw payload). It distinguishes itself by detailing filtering options and the mark_read flag, making the purpose specific and distinct 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 explains when to use the tool (e.g., 'Polls work fine') and provides an alternative access method (direct API at registry.pipeworx.io). It does not explicitly state when not to use it, but the context is clear.

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

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

The description discloses that the tool fans out to multiple sources (SEC, GDELT/GNews, USPTO), explains the fallback logic, and notes that USPTO's PatentsView API will sunset in May 2025 causing a soft-fail. It also mentions the return structure (changes[] grouped by source, total_changes, citation URIs). All annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with the description.

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

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

The description is front-loaded with examples and purpose, but it is somewhat long (several sentences). However, every sentence adds meaningful information, and the structure is clear. It could be trimmed slightly but is effective 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?

Given the tool has three required parameters with full schema coverage, no output schema, and moderate complexity (multiple data sources, fallback, time window), the description provides complete context: what the tool does, how to invoke it, what to expect in return, and how it differs from a sibling tool. No gaps remain.

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

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

Schema description coverage is 100%, but the description adds extra value: for 'since' it explains ISO date and relative shorthand formats ('7d', '30d', '3m', '1y'), and for 'value' it clarifies it can be a ticker or CIK. The description also notes the 'type' is restricted to 'company'. This goes 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 starts with explicit query examples ("What's new with X", "latest on Y") and states it provides a change feed for a company in a time window. It clearly differentiates from the sibling tool 'entity_profile' by specifying that entity_profile is for static profiles regardless of window.

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 includes direct guidance: 'Use entity_profile instead when you want the static profile... regardless of window.' It also provides example queries and notes the fallback behavior (GDELT preferred, GNews on failure). This tells the agent when and when not to use the tool.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so no risk of duplication or destruction. Description adds context: scoped by identifier, persistence details, and pairing info, which is valuable but not critical 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 a single paragraph that front-loads the purpose. Every sentence contributes value, though it could be slightly tighter without losing information.

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

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

For a simple write tool with no output schema, the description covers all necessary context: persistence, scoping, pairing with siblings, and example usage. It is fully adequate for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with descriptions for both key and value. The description adds context by mentioning key-value pair and providing example keys, but does not add substantial new 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 saves data for later reuse across conversations or sessions, using specific verb 'save' and resource 'data'. It distinguishes itself from sibling tools like recall and forget by mentioning pairing.

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: 'when you discover something worth carrying forward'. Provides alternatives: 'Pair with recall to retrieve later, forget to delete'. Also explains persistence differences for authenticated vs anonymous sessions.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. The description adds value by disclosing internal cascading through multiple endpoints, auto-disambiguation, and specific return fields for each type, which are not in annotations.

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

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

The description is front-loaded with examples and structured well. Each sentence adds value, but it is slightly verbose. Still, it balances completeness with conciseness.

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

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

Given the complexity of two entity types with different outputs and no output schema, the description covers return details (ticker, CIK, RxCUI, citations) and input formats thoroughly. It is complete enough for an agent to understand what to expect.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema by explaining acceptable inputs for each type (e.g., ticker, CIK, name for company; brand or generic name for drug) and detailing the returned fields and citation URIs.

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 resolves names to canonical identifiers, provides concrete examples ('ticker for company', 'RxCUI for drug'), and distinguishes it from sibling tools by instructing to use it first when needing an ID.

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 given: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups. However, it does not explicitly discuss when not to use or compare to specific sibling tools.

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

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

Annotations already indicate safe, idempotent behavior. The description adds that it calls ai_visibility_check per entity and returns a 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?

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value without redundancy.

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

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

Given the tool's complexity and lack of output schema, the description adequately covers what it does, how it works (probes with ai_visibility_check), and the output format (ranked list). It could mention pagination or error handling, but it's sufficient for most use cases.

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 description is not required to add much. However, it provides valuable context: explains that the first entity in 'entities' is the subject and the rest are competitors, and clarifies the 'models' parameter usage and API key dependency. This adds 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 it compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks them. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 a clear use case ('competitive AI-marketing audits') and an illustrative example. However, it does not explicitly mention when not to use this tool or discuss alternatives beyond the implication from sibling names.

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

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

Adds significant behavioral context beyond annotations: fans out across two services, returns specific fields, handles partial failures gracefully, mentions bundlephobia's first measurement can take 5-30s and sources_failed list. 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?

Dense but effective, front-loads purpose. Every sentence adds value, though slightly long. Could be slightly more structured but remains 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 return fields (summary block, per-advisory, links, alternative versions) and error handling. Fairly complete for a tool with 2 params.

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% coverage (both parameters described). Description adds minimal extra meaning (e.g., version defaults to latest is already in 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?

Description clearly states it is a composite check for npm packages, answering whether to add a package. It specifies the verb 'scan' and resource 'dependency'. Distinguishes from siblings (no other tool does package security/size checks) and explicitly limits scope to 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?

Explicitly states when to use: 'when an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also gives when-not-to-use: for other ecosystems, use deps.dev:version directly. Provides context on partial failures and timing.

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

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

Annotations already provide safety hints, but the description adds significant behavioral detail: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagged, and return format including character offsets and similarity scores.

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

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

Three compact sentences: purpose, use case, technical details. Every sentence adds value; 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?

With no output schema, the description fully explains return values (passages, offsets, scores), processing details, and constraints. Complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds value with max chars for 'text' (200K), default and range for 'limit' (1-20, default 5), and example queries for 'query'.

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 'Semantic search INSIDE a fetched record' and gives examples like SEC 10-K. However, it does not explicitly differentiate from siblings like 'find' or 'get_entry', only mentioning pairing with 'ask_pipeworx_grounded'.

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

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

Explicitly advises 'Use when the record is too big to cram into the prompt' and mentions truncation cap. It references a complementary tool but does not list specific exclusions or alternatives.

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

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

The description adds significant behavioral context beyond annotations: requires specific account type, delivery channels with constraints (email validation, SMS verification, webhook HMAC signing and auto-disable after 10 failures). It also notes that webhook secret is returned only once. These details are not present in annotations and provide essential behavioral transparency.

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

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

The description is dense with information but not overly verbose. It front-loads the main purpose and then details types and delivery. Some might consider it slightly long, but it is well-structured for usability.

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 and lack of output schema, the description covers purpose, requirements, types, delivery options, and important constraints. It does not explicitly describe the response format beyond 'Returns the new subscription id', but that is typical for such tools. Error cases are not mentioned, but overall it is complete enough 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?

Although schema coverage is 100%, the description adds substantial meaning with concrete examples for each 'type' in the 'params' property and explains the 'delivery' object in detail, including constraints and caveats (e.g., SMS cap, webhook signing). This goes well 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 verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It also specifies that it returns a new subscription id, and the list of supported types distinguishes it from 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?

The description explains when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account; anonymous/BYO cannot persist). It does not explicitly state when not to use, but the context and sibling tools imply alternatives. The detailed type-specific usage and delivery channels provide clear guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond these by stating that the tool returns example questions with exact tool+argument shapes drawn from a live catalog, which is useful behavioral context. However, it does not delve into potential errors or edge cases.

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

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

The description is front-loaded with common questions and is well-structured. However, it is somewhat verbose, listing many categories and examples, which could be trimmed without losing meaning. Still, every sentence contributes 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 optional parameter, no output schema), the description is complete. It explains the return value, when to use, and how to use. No gaps remain.

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

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

Schema description coverage is 100% (the topic parameter's description is present). The description goes further by listing example values (finance, pharma, etc.) and clarifying that omitting the parameter gives a spread. This adds 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 that the tool returns category-bucketed example questions and is the onboarding entry point for a new agent. It uses specific verbs ('returns', 'call') and the resource ('example questions') is well-defined. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by positioning itself as the first tool to use when unsure.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use with or without the topic argument. It also mentions that the tool teaches how to call meta-tools, providing clear context for 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?

Adds that row is deactivated, not deleted, and historical events remain via recent_alerts. Aligns with annotations (destructiveHint false, readOnlyHint false). Could mention idempotency from annotations.

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

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

Two sentences, no fluff, front-loaded with key action and constraints.

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?

Complete for a simple one-param tool with no output schema; covers ownership, effect, and integration with 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 already fully describes parameter; description adds context that id is from subscribe but doesn't go 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?

Clear verb (Cancel/unsubscribe) and resource (subscription by id). Distinguishes from sibling 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?

Explicitly states ownership enforcement and that the row is deactivated (not deleted), guiding when to use. Implicitly contrasts with delete or full removal.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description doesn't repeat that. It adds value by detailing return structure (verdict, extracted form, actual value with citation, percent delta) and data sources (SEC EDGAR + XBRL). Notes v1 limitations, providing full behavioral context.

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 front-loaded with trigger phrases and efficiently structured. Every sentence serves a purpose: examples, usage guidance, scope, return explanation, efficiency comparison. Could be slightly more concise, but it's well-organized.

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

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

Given the simple single-parameter input, no output schema, and comprehensive annotations, the description covers all necessary aspects: purpose, usage, behavioral details, return structure, and limitations. It is complete for the tool's complexity level.

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

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

The single 'claim' parameter has 100% schema description coverage. The description adds examples and clarifies it's a natural-language factual claim, reinforcing the schema. No enums or nested objects, so minimal additional semantics needed, but the examples are helpful.

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 claim verification with specific examples like 'Is it true that…' and 'fact check'. It specifies the domain (company-financial claims for public US companies) and distinguishes from siblings by noting it replaces 4-6 sequential calls, making it a specialized tool.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides trigger phrases. It implies when-not-to-use by specifying the scope (v1 supports company-financial claims), though no explicit alternatives are given. Clear context for usage.

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