Alienvault Otx

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false, so the agent knows it's safe and non-destructive. The description adds behavioral context beyond annotations: default model ('Workers AI Llama-3.3-70b'), that Anthropic requires a BYO key paid directly to Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 three sentences with no wasted words. It front-loads the primary action ('Probe one or more LLMs for what they know... and score visibility'), then details default model and key requirements, and ends with use cases. 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?

There is no output schema, so the description must explain return values. It does so succinctly: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' It also covers parameter usage and use cases. For a tool probing LLMs with 4 parameters, this provides sufficient context for an agent to invoke it correctly.

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

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

Schema description coverage is 100% (all four parameters have descriptions). The tool description adds further meaning: explains the `entity` parameter as a brand/business/product/person/topic, clarifies `models` can be omitted for just workers-ai, and specifies `_apiKey` is only needed when probing Anthropic and is passed straight through. This goes beyond the schema alone.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model. The verb 'probe' and resource 'visibility of entity across models' are specific. Among siblings, it distinguishes from similar tools like 'scan_competitor_ai_presence' by focusing on scoring a single entity across models.

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

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

The description provides clear context for use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also specifies when to use the `_apiKey` parameter (if probing Anthropic). However, it does not explicitly state when not to use this tool versus alternatives like 'scan_competitor_ai_presence', missing a direct exclusion.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, etc. Description adds that it routes to 3804 tools across 907 sources and returns structured answers with stable citation URIs, which is valuable context beyond annotations. No contradictions.

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

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

Somewhat long but well-structured with key guidance front-loaded and every sentence adding value. Could be slightly trimmed without loss, but no filler.

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

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

Given no output schema, description adequately covers return format (structured answer with citation URIs). With rich annotations and schema, it covers most needs. Could mention that it handles single-turn queries vs research tasks (sibling deep_research exists).

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 aliases described. Description reinforces that the parameter is a natural language question and gives examples, adding meaning beyond the schema. Could mention expected input format more precisely but sufficient.

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 answers factual questions using authoritative data, with specific verb 'ask' and resource 'Pipeworx'. It distinguishes from web search and provides concrete examples, making purpose unmistakable.

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

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

Explicitly says to prefer over web search for factual queries and lists many domains. Provides usage examples. However, it does not contrast with sibling tools like lookup_indicator or deep_research, leaving some ambiguity about when to use which.

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 and idempotentHint. The description adds valuable behavioral context: costs one extra LLM call, returns explicit refusal reasons, and only extracts answers from tool results. 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 moderately long but well-structured with front-loaded purpose. Every sentence adds value, though some detail on routing could be condensed. Still efficient for the information provided.

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 high schema coverage and no output schema, the description compensates by detailing the return format and explicit refusal reasons. It covers error types and use cases, making it complete for a question-answering tool.

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

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

Schema coverage is 100% with all parameters being aliases for 'question'. The description mentions that the question is in natural language and lists aliases (q, prompt, text, input, query), which adds minimal extra value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads. It specifies the verb 'ask' and resource 'Pipeworx Grounded', and distinguishes it from the sibling tool ask_pipeworx by noting the extra LLM call and use cases for quotes/citations.

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: 'whenever an answer will be quoted, cited, or acted on' with examples (financial verdicts, legal claims, medical lookups, public statements). Also advises to prefer ask_pipeworx for casual lookups, providing clear differentiation.

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

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

Annotations already mark it as read-only and idempotent. The description goes far beyond by detailing fan-out logic, market resolution, blocking conditions (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), resource-rule risk (cancellation_rule), and safety mechanisms. This is exceptionally transparent.

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

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

The description is very long and dense, covering many details. It front-loads the purpose and usage, but the extensive technical elaboration makes it less concise. However, the length is justified by the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains response shapes (result.market, analysis, evidence), edge cases (low-confidence, closed markets, wide spreads), and important fields to inspect (market_match_confidence, cancellation_rule). It covers all necessary context for correct 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?

Schema covers all three parameters with descriptions (100% coverage). The description adds value by explaining the depth enum (quick vs thorough), market input formats, and the include_raw trade-off, enriching what the schema provides.

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

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

The description clearly states the tool's core action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' Specific use cases ('should I bet on X') and input types (slug, URL, question text) are provided, distinguishing it from sibling tools like polymarket_edges or deep_research.

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

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

The description explicitly says 'Use for' scenarios and provides detailed sub-use cases. It does not directly compare to siblings, but it implies exclusivity for individual bet research. Guidance on when not to use (low-confidence matches, closed markets) is included.

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 non-destructive behavior. The description adds context about specific data fields (revenue, net income, etc.), handling of off-calendar fiscal years, and citation URIs. No contradiction.

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

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

The description is front-loaded with example queries and is concise yet comprehensive. Every sentence adds necessary 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?

For a tool with no output schema, the description clearly states that returns include paired data and citation URIs, and explains sorting. It covers input, output, and behavioral details adequately.

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 meaning: explains that 'type' determines data sources (company vs drug) and clarifies that 'values' expects tickers/CIKs for companies and drug names, with 2-5 items. This goes beyond schema descriptions.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs, with specific examples like 'X vs Y'. It distinguishes from sequential lookups and specifies data sources (SEC EDGAR for companies, FAERS for drugs).

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a strong usage guideline. It also explains result sorting by primary metric, helping agents know what to expect.

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 critical behavioral context: it decomposes questions, fetches evidence verbatim, never invents, returns gaps for unanswered facets, and provides stable citations. It also discloses the expected latency (15-60s) and account requirements, which go 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 efficient, front-loading the main purpose and process. Every sentence adds value: it explains what the tool does, when to use it, prerequisites, and expected output. Minor length is justified by the need to explain a complex parallel research process.

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

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

The tool is complex with parallel decomposition and multi-source grounding. Despite no output schema, the description covers the return structure (structured findings packet with evidence, confidence, source, fetched_at, citation, gaps). It also addresses account requirements, plan limitations, and expected latency. All essential context is present.

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

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

Schema description coverage is 100% and already defines both parameters. The description adds value by explaining the depth enum (quick=3, standard=5, thorough=8 with paid plan) and clarifying that the question should be in natural language and can be broad or multi-part. This extra context justifies a score above the baseline of 3.

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

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

The description clearly states the tool performs 'grounded multi-source research' and explains the process of decomposition, parallel tool routing, and extraction of grounded answers. It distinguishes itself from the sibling tool ask_pipeworx by noting that deep research is for broad/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?

Provides explicit guidance on when to use this tool ('broad or multi-part questions') and when not to ('use ask_pipeworx for single lookups'). It also gives example questions and mentions prerequisites (Pipeworx account, paid plan for thorough depth).

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

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

Annotations declare readOnlyHint=true and idempotentHint=true. Description adds that the tool returns top-N tools with full schemas and examples, ready to call directly—beyond what annotations convey.

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

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

Description is concise (few sentences), front-loaded with purpose, and uses bullet-style listing without waste. Every sentence adds value.

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

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

Given the tool's complexity (6 parameters, no output schema), the description fully covers what to expect (return format, readiness for direct call, when to use). Highly complete.

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

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

Schema coverage is 100% so baseline is 3. Description only adds that query is a 'Natural language description' and mentions limit implicitly via schema; no significant extra meaning beyond schema.

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

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

The description clearly states 'Find tools' and elaborates with specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools like search_pulses or deep_research that focus on search within content rather than tool discovery.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', providing clear context. Does not state when not to use, but the positive guidance is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF), notes the USPTO PatentsView API sunset with a soft-fail behavior, and details the exact return fields. 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 relatively long (multiple sentences) but front-loaded with example queries. Every sentence provides useful information, though some details (like the specific fields returned) could be slightly more compact. Still, it earns its length.

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

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

Given the tool's complexity (multi-source, no output schema), the description covers all essential aspects: what it does, when to use it, the exact inputs, the data sources consulted, the return fields, and limitations. No gaps remain.

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

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

Schema coverage is 100%, so both parameters are described in the schema. The description adds value by reinforcing that type must be 'company' (not person/place) and that value must be a ticker or CIK, and explains why names are not supported (use resolve_entity). This adds context beyond the schema.

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

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

The description starts with concrete example queries and clearly states it returns a 'full cross-source profile of a US public company'. It uses a specific verb ('return') and resource ('profile'), and distinguishes itself from sibling tools like resolve_entity (which handles name resolution) and compare_entities.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view'. Also provides a clear when-not-to-use: 'Names not supported (use resolve_entity first if you only have a name)'. This gives clear context and alternatives.

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

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

Annotations already indicate destructiveHint=true, so the description's confirmation of deletion adds context about clearing sensitive data and staleness. No contradiction with annotations.

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

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

The description is two sentences: first states the action, second gives usage guidance. It is concise and front-loaded with no unnecessary 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 tool with one parameter and annotations present, the description is complete. It explains what it does, when to use it, and references siblings. No output schema is needed as the tool is likely void.

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 'key' parameter as 'Memory key to delete'. The description only mentions 'by key', adding no new semantic information beyond what the schema provides.

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

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

The description clearly states the action 'Delete a previously stored memory by key', which is a specific verb and resource. It also distinguishes from siblings by mentioning pairing with remember and recall.

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

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

The description provides explicit context for when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also references sibling tools (remember, recall) for pairing, though it does not include explicit when-not-to-use scenarios.

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

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

The description explicitly states that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This adds behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) and is consistent with them. No contradictions found.

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

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

The description is three sentences plus a bullet list of use cases. It is reasonably concise and front-loads the primary action. Every sentence adds value, but the structure could be slightly more compact. Still, no extraneous 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 simplicity of the tool (2 params, safe annotations, no nested objects) and the absence of an output schema, the description provides sufficient context: it explains the high-level process and output format. However, it lacks details on error handling (e.g., invalid URL) and rate limits, which would be useful for an AI agent, but these are not critical for a read-only, idempotent tool.

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

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

The input schema already has 100% description coverage for both parameters (url and max_links). The description does not add any additional semantic meaning beyond what the schema provides, such as examples or constraints. According to the rubric, baseline 3 is appropriate when schema coverage is high.

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

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

The description clearly identifies the tool's purpose: generating an llms.txt file for a given URL. It specifies the target AI crawlers (ChatGPT, Claude, Perplexity) and the output format (standard llms.txt markdown). This distinguishes it from sibling tools, none of which generate llms.txt files.

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 a 'Useful for' section listing three concrete use cases (getting a client's site indexed, drafting for own project, auditing competitor). While it does not explicitly state when not to use the tool or compare to siblings, the use cases provide clear guidance on appropriate 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, making the behavioral profile clear. The description adds no new behavioral traits beyond listing output fields, so minimal added 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?

A single sentence that front-loads the action and lists key content, with no wasted words.

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

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

Given the simple one-parameter schema, comprehensive annotations, and presence of an output schema, the description provides sufficient context for a retrieval operation.

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

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

With 100% schema description coverage (the single parameter 'pulse_id' is described as 'OTX pulse ID (hex string)'), the description does not add additional parameter 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 'Fetch a single OTX pulse' and enumerates the returned data (description, references, indicators, etc.), which differentiates it from sibling 'search_pulses' for searching multiple pulses.

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

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

The description implies usage for retrieving a specific pulse by ID, and the presence of 'search_pulses' as a sibling provides implicit guidance, but there is no explicit when-to-use or when-not-to-use statement.

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, idempotentHint, destructiveHint. Description adds that by default only active subscriptions are returned and lists output fields, adding value beyond annotations.

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

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

Two sentences with no waste; first sentence states action and output, second provides usage guidance. Efficiently 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?

Simple tool with one optional param; description lists return fields. No output schema, but fields are provided. Lacks mention of pagination or sorting, but still fairly complete.

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

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

Schema coverage is 100%; the only parameter 'include_inactive' has a description. The tool description does not add new parameter details, so baseline score applies.

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

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

The description clearly states it lists active subscriptions with specific fields, and it distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly advises when to use: to review monitoring before adding more or to find an id to cancel. Lacks explicit when-not, but context is sufficient.

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

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

Annotations declare read-only, open world, idempotent. Description adds that it returns pulses and observed-context fields, and mentions auto-detection behavior. Adds useful context beyond annotations.

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

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

Two concise sentences, front-loaded with core purpose, no filler 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?

With 2 parameters, output schema present, and clear description covering purpose, parameter behavior, and return content, the description is fully complete for this lookup 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. Description adds that type is auto-detected when omitted and indicator can be IPv4, domain, URL, or file hash, which clarifies accepted values beyond the schema enum.

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 verb 'look up', resource 'indicator in OTX', and lists accepted types (IPv4, domain, URL, file hash). Distinguishes from siblings like search_pulses by focusing on direct indicator lookup.

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

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

Provides context that type is auto-detected when omitted, guiding when to include the type parameter. However, no explicit mention of when to use this tool versus alternatives.

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

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

Annotations are all false, so the description carries full burden. It discloses rate limits (5 per day per identifier), cost (free, no quota), and how feedback is processed (daily digests, affects roadmap). 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 a single paragraph but well-structured: purpose first, then usage, then constraints. Every sentence adds necessary 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?

For a feedback tool with no output schema, the description fully covers what the tool does, how to use it, limitations, and outcomes. No gaps.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining enum values (e.g., 'bug = something broke') and message length expectations (1-2 sentences, 2000 chars max). It does not elaborate on the context object beyond the schema, so not a 5.

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, features, data gaps, or praise to the Pipeworx team. It distinguishes itself from sibling tools by focusing on feedback rather than data retrieval or 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 guidance on when to use each feedback type (bug, feature, data_gap, praise) and instructs not to paste end-user prompts. It also mentions rate limits and quota-free usage, but does not compare to alternatives directly, though 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: source (CF analytics-engine), no PII, caching duration (5min-1h), and the data format (pack, tool, count). 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, front-loaded with the core purpose, and every sentence provides useful information without redundancy. It efficiently conveys the tool's value and behavior.

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

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

Despite having no output schema, the description explains what is returned (top tools, top packs, total call volume) and caching details. Given the tool's simplicity (one optional parameter), the description is fully complete.

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

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

Schema coverage is 100% with one parameter 'window'. The description adds meaning beyond the schema by explaining that shorter windows surface current trends and longer windows show steady-state demand, enhancing the agent's understanding.

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

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

The description clearly states the tool's purpose: returning top tools, packs, and call volume over a recent window. It uses specific verbs ('returns') and identifies the resource, distinguishing it 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?

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and notes the source (CF analytics-engine) and caching behavior, providing clear guidance for when to use this tool.

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

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

Extensively describes internal logic (monotonicity checks, partition sum, Jaccard similarity, placeholder filtering, fill check against live CLOB depth). Annotations already indicate read-only and idempotent; description adds actionable constraints like not trading when realizable_edge_pp <= 0.

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

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

Well-structured with front-loaded requirement, clear mode separation, and logical flow. However, the description is lengthy and dense; some detail (fill check logic) could be more concise.

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

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

Covers all aspects: argument requirements, mode selection, internal logic, response fields (opportunities, partition_check), edge cases (low similarity, placeholder filtering), and fill check tradability. No output schema, so description compensates fully.

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 descriptions already provide basic meaning (100% coverage), but description enriches with concrete examples, mode semantics, and behavioral implications, adding significant value beyond schema alone.

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

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

Description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes between event (single-market) and topic (cross-event) modes. However, it could better differentiate from sibling tools like polymarket_edges or polymarket_kalshi_spread, though it does mention polymarket_fill_risk for custom sizing.

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 requirement for one of event or topic, provides mode selection guidance with concrete examples, and references sibling tool polymarket_fill_risk for custom sizing, establishing clear when-to-use and when-not-to-use.

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

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

Annotations indicate read-only, idempotent, open-world, and non-destructive behavior, which the description supports. The description adds significant behavioral context: caching, response segmentation, model family details, diagnostics for empty segments, and edge calculation specifics. 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 overly long and dense, mixing purpose, model details, parameter guidance, and response structure into a single paragraph. While informative, it lacks conciseness and would benefit from structured formatting like 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?

Given the complexity (9 parameters, no output schema), the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics), why segments may be empty, and the meaning of key fields. It compensates for the lack of output schema with detailed textual description.

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 has 100% coverage with detailed descriptions. The description adds extra context beyond the schema, such as explaining how slippage is applied, why min_partition_leg_kelly is needed for partitions, and that edge is net slippage. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: scanning top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses a specific verb-resource combination and distinguishes from siblings like polymarket_arbitrage by focusing on edge detection within Polymarket.

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

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

The description explicitly says when to use ("what should I bet on today") and implies when not to (Fed bets excluded due to unreliable signal). It provides caching details but does not directly name sibling tools as 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 and idempotentHint, and the description adds substantial behavioral context: reading from daily snapshots, 60-day TTL, decay computed from daily closes (not intraday), trend based on absolute value, and snapshot gaps. No contradictions with annotations.

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

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

The description is dense but well-structured, starting with the key question, then detailing response fields (tracked, expired, snapshot_dates), and ending with limits. Every sentence adds value, though slightly long.

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, so the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) with field meanings and computation details. It also covers limits like 60-day TTL and snapshot behavior, making it self-contained for the tool's complexity.

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

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

Schema covers both parameters with descriptions. The description adds extra context: default and max for days (though slight inconsistency with schema clamp), default window family, and clarifies that window refers to snapshot family. This extends understanding beyond schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on historical analysis and decay trends.

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

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

The description implies usage context by stating that a fresh wide edge and an old wide edge are different trades, guiding when to use this tool for understanding edge history. It also explains snapshot gaps due to cache-miss, but does not explicitly state when not to use or mention alternatives among siblings.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description's job is to add behavioral context beyond those. It does so by disclosing that thin books may make theoretical overround uncapturable, that partial fills create directional risk, and it explains the verdicts (clean|degraded|cannot_fill). However, 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 front-loaded with a concise one-liner followed by structured mode explanations. It is informative but somewhat dense; every sentence earns its place, though it could be slightly more compact without losing key details.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is comprehensive. It enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk, etc.) and explains the risk scenarios in detail.

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

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

Schema description coverage is 100%, but the description adds operational meaning: it explains how the side parameter defaults differ between single-market and basket modes, how size_usd is interpreted differently (spend vs proceeds vs settlement notional), and provides context like clamping range. This adds value beyond the schema.

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

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

The description clearly identifies this tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with specific usage, and it is differentiated from sibling tools like polymarket_arbitrage and polymarket_edges by its role as a risk check before acting on their signals.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides reasoning for when not to use it, explaining that partial basket fills convert an arb into directional risk, which is the dominant loss 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description details safety fields like compatibility_warning, temporal_alignment, and skipped_cross_type/cross_subtype. It explains precisely when these fire, adding significant behavioral context. No contradiction with annotations.

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

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

The description is detailed and well-structured, with clear sections for modes, response, and safety fields. While lengthy, the complexity of the tool warrants the detail. Every sentence adds necessary information, so it is appropriately concise for its purpose.

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

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

Despite no output schema, the description thoroughly covers input modes, response structure (leg-by-leg prices, spread, safety fields), and important caveats (compatibility, temporal alignment, skipped comparisons). An agent can fully understand how to invoke and interpret results.

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

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

All three parameters have descriptions in the schema (100% coverage), so baseline is 3. The description adds value by explaining the two modes, the list of topic shortcuts, and that explicit tickers override topic mapping. This extra context justifies a score of 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 it measures cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains the response format. This differentiates it from sibling tools like polymarket_arbitrage.

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 (to compare prices across venues) and includes warnings about compatibility and temporal alignment. While it implies when not to use (e.g., when bet shapes are non-equivalent), it does not explicitly mention alternatives like polymarket_arbitrage. Nevertheless, the guidance is clear and practical.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds scoping detail (anonymous IP, BYO key hash, account ID) and dual behavior (retrieve vs. list). No contradictions.

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

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

Two sentences: first states core functionality, second provides context and alternatives. Every word serves a purpose 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?

Given no output schema, the description sufficiently explains return behavior (value or list of keys). Covers scoping and pairing with siblings, making the tool fully understandable.

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?

Only one parameter 'key' with schema description; description explains that omitting it lists all keys, adding functional meaning beyond the schema's type/description.

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

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

The description clearly states the tool retrieves a saved value by key or lists all keys when omitted. It explicitly names the companion tools 'remember' and 'forget', distinguishing its role from siblings.

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

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

Provides concrete use cases: retrieving user's target ticker, address, research notes. Explicitly states to use when context was stored earlier, avoiding re-derivation. Could be improved by stating when not to use, but overall 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 describes 'mark_read:true' as flagging events read, which is a state change, contradicting the 'readOnlyHint: true' annotation. This is a serious inconsistency.

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 purpose and is fairly concise with 5 sentences, each adding information. The alternative endpoint info is secondary but not excessive.

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 explains return content and the 'mark_read' effect but omits 'unread_only' parameter and does not detail limit behavior. It is adequate but has gaps given the tool has 5 optional parameters and no output schema.

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

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

The schema has 100% coverage, so baseline is 3. The description adds value by explaining the effect of 'mark_read', giving an example for 'type', and clarifying 'since' expects ISO timestamps. It does not mention 'unread_only' but overall enhances parameter understanding.

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

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

The description clearly states the tool pulls fired events from the subscription feed and specifies the return content (source, citation_uri, raw payload). It distinguishes from siblings like 'list_subscriptions' and 'recent_changes' by focusing on recent alerts from 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 mentions that polling works fine and provides an alternative external endpoint, giving context on when to use the tool. However, it does not explicitly compare with siblings or state when not to use it.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds valuable details: sources (SEC, GDELT→GNews fallback, USPTO), behavior of PatentsView API sunset, and return structure. 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?

Description is verbose but front-loaded with example queries and logically structured. Every sentence adds value, though some redundancy could be trimmed without loss.

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 multi-source fan-out, fallback logic, and soft-fail behavior, the description covers all important aspects. No output schema exists, but return structure is described.

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, but the tool description adds more: explains 'since' with relative shorthand examples ('7d', '30d', '3m', '1y'), clarifies 'type' is only 'company', and describes 'value' as ticker or CIK.

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

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

The description clearly states it is a change feed for a company, covering SEC filings, news, and patents. It distinguishes from the sibling tool 'entity_profile' by explicitly noting when to use each.

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 query examples (e.g., 'What's new with X', 'latest on Y') and directly advises to use 'entity_profile' for static profiles. Offers clear when-to-use guidance.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: scoping by identifier, persistence duration for anonymous sessions (24 hours), and that it is a key-value store. 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 three sentences, front-loaded with the core purpose. It is clear and efficient, though could be slightly more concise by merging some details.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description fully covers its purpose, usage, behavior, and how it integrates with sibling tools. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds helpful examples for key and value (e.g., 'subject_property', 'target_ticker') and mentions scoping, providing extra 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 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from sibling tools like recall 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 explicitly tells when to use ('when you discover something worth carrying forward') and provides context for persistence differences between authenticated and anonymous sessions. It also guides pairing with recall and forget.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context that each call cascades through multiple lookups and replaces 2-3 manual steps, plus mentions auto-disambiguation.

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 examples up front and organized details. It is slightly verbose but each sentence adds value.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers what the tool does, what inputs are expected, and what outputs are produced for each type, including citation URIs.

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 significantly enriches both parameters: it explains the return structure per type (e.g., for company includes ticker, CIK, name, citation URI) and mentions auto-disambiguation.

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, with specific examples (ticker, CIK, RxCUI). It distinguishes itself from siblings by being the go-to for name-to-ID conversion.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance. It does not explicitly list alternatives, but the context makes it apparent.

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, idempotentHint, and destructiveHint=false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns ranked list with score, confidence, signal density. No contradictions, and it provides behavioral details beyond annotations.

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

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

The description is three sentences, front-loaded with the core action. It includes an example question, which adds value without being verbose. Could be slightly more concise, but it's well-structured.

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

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

Given the tool has 4 parameters, no output schema, and moderate complexity, the description covers the main behavior (what is returned: ranked list with score, confidence, signal density) and the use of the 'entities' parameter. It adequately prepares the agent for invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context that the first entity in 'entities' is treated as the 'subject' for narrative purposes, which adds meaning beyond the schema. It also ties the parameters to the ai_visibility_check probe behavior.

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

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

The description clearly states the tool compares AI visibility across multiple entities, ranks them, and identifies the most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (different 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?

The description explicitly mentions 'useful for competitive AI-marketing audits' and provides a concrete example question. It does not explicitly state when not to use it, but the context implies it's for competitive analysis. Alternatives like ai_visibility_check are implied but not named.

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, non-destructive, idempotent, and open-world. The description adds critical behavioral context: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This goes beyond annotations and fully informs the agent of expected behavior.

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

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

The description is information-dense but structured: starts with the composite nature, lists use cases, then details return fields and failure modes. Every sentence adds value, though the length is justified by the tool's complexity. Minor improvements could be more bullet-pointed structure.

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

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

Despite lacking an output schema, the description enumerates all returned fields, mentions potential delays and graceful degradation, and covers versioning and scope. It provides sufficient context for an agent to understand what to expect and how to handle edge 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% with descriptions for both parameters. The description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted and that version defaults to latest. While not exhaustive, it complements the schema well.

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

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

The description clearly states it is a composite check for evaluating whether to add an npm package, aggregating data from deps.dev and bundlephobia. It lists specific return fields and distinguishes scope (NPM ecosystem only). This precisely conveys the tool's purpose and differentiates it from siblings.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear guidance on when to choose this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveness. The description adds context about the specific fields returned (e.g., pulse ID, indicator count), which goes beyond annotations. No contradictions.

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

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

Single sentence front-loads the action but includes a list of return fields which, while helpful, adds length. Could be slightly more concise by listing fewer examples, but overall efficient.

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

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

With 3 parameters fully described in schema, output schema present, and annotations covering safety, the description provides a complete understanding of what the tool does and returns. Could mention pagination behavior, but schema covers page/limit.

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 additional meaning beyond what the schema already provides for 'page', 'limit', and 'query' parameters. Example usage in schema further clarifies.

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

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

Clearly states the verb 'Search', the resource 'OTX threat-intel pulses', and lists specific returned fields ('pulse ID, name, description preview, tags...'). Differentiates from sibling 'get_pulse' which likely retrieves a single pulse.

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?

Implies usage for searching by keyword but provides no explicit guidance on when to use this tool versus alternatives like 'deep_research' or 'compare_entities'. Lacks when-not-to-use or prerequisite information.

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

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

Annotations already indicate readOnly, idempotent, etc., but the description adds rich behavioral detail: embedding model (BGE-base-en), algorithm (cosine over 500-char windows), character cap (200K chars with truncation flag), and return format (character offsets, similarity scores). 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?

Single paragraph, well-organized: starts with primary action, then use case, benefits, pairing, and technical specifics. Every sentence adds value, no redundancy. Front-loaded with 'Semantic search INSIDE a fetched record' for immediate understanding.

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

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

Despite no output schema, the description explains return values (top-N passages, offsets, scores) and constraints (character cap, truncation). Given the tool's moderate complexity and three parameters, it covers all necessary details for effective invocation.

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

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

Schema coverage is 100%, baseline 3. The description adds value by providing example queries for the query parameter (e.g., 'supply-chain risk'), clarifying the text parameter's max length and truncation behavior, and specifying default and range for limit. These additions aid correct usage beyond schema alone.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verb+resource (Search Within a Source). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded, and provides concrete examples like SEC 10-K body, making the purpose unmistakable.

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

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

Explicitly states when to use (record too big for prompt) and explains benefits (saves context, returns only relevant passages). It suggests a workflow with ask_pipeworx_grounded, providing guidance on integration. Lacks explicit 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?

Beyond annotations, description details account prerequisites, supported event types with examples, delivery channels (feed, email, SMS, webhook), SMS cap of 10/day, webhook auto-disabling after 10 failures, and one-time secret retrieval. Annotations only hint at write behavior and idempotency.

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 purpose and return value, then organized into requirements, types, and delivery sections. Slightly verbose but each sentence adds value; could be tighter but no waste.

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

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

Given full schema coverage and no output schema, description covers input parameters thoroughly, includes key behavioral details (requirements, limits, webhook setup), but omits nothing critical. The return value is simply described as the subscription ID, which is sufficient.

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

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

Adds significant meaning beyond the input schema: explains enum values with real examples (e.g., sec_8k items codes, polymarket_edge topics), parameter structures for each type, and delivery sub-field details (SMS verification, webhook signing). Schema coverage is 100% but description enriches it.

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 creates a proactive monitoring subscription and returns the new subscription ID, distinguishing it from sibling tools like list_subscriptions (listing) and unsubscribe (deleting).

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?

Describes when to use (subscribing to alerts), required account type (Pipeworx OAuth), and implicitly differentiates from siblings. Does not explicitly list exclusions but provides sufficient context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds value by describing the return format (category-bucketed questions with tool+argument shapes) and the optional topic parameter behavior. This goes beyond annotations without contradicting them.

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

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

The description is relatively long, including a list of nine category examples and several alternative query phrases. While front-loaded with the most critical information ('onboarding entry point'), the detailed enumeration makes it less concise than ideal. Every sentence adds context, but the length could be trimmed.

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

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

For a tool with only one optional parameter and no output schema, the description is remarkably complete. It covers: when to use, what it returns (example questions with tool shapes), how to call it (no args vs. topic), and even mentions sibling meta-tools ('ask_pipeworx, entity_profile, compare_entities'). 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?

The input schema already fully describes the single parameter 'topic' with a clear description and enumerated examples. The description reinforces this by listing the topic values inline. Since schema coverage is 100%, the description adds minimal new semantic meaning beyond providing repeated examples.

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 multiple natural language queries ('What can I ask Pipeworx?') and clearly states it is 'the onboarding entry point' that returns 'category-bucketed example questions' with exact tool+argument shapes. This makes the purpose immediately understandable and distinguishes it from other tools like 'ask_pipeworx' or 'discover_tools'.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also provides specific invocation patterns: 'Call with no arguments for the full spread, or pass topic...' and lists example queries that trigger it. No when-not stated, but the context of being an entry point makes exclusion implicit.

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

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

Discloses important behavioral traits beyond annotations: ownership enforcement, deactivation (not deletion), and preservation of historical data. No contradiction with annotations.

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

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

Two concise sentences with no wasted words. Front-loaded with the core action and resource.

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?

Completes the context for a simple, single-parameter tool: explains side effects, ownership rules, and where historical events remain available. No gaps.

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

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

Schema coverage is 100% and description adds minimal meaning beyond schema ('Subscription id returned by subscribe'). Baseline score of 3 applies.

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

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

Clearly states the action (cancel) and resource (subscription by id). Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Specifies ownership enforcement and that only own subscriptions can be cancelled. Mentions behavioral nuance (deactivation vs deletion). Could be improved by explicitly stating when not to use, but sufficient.

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

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

The description adds significant behavioral context beyond annotations: it specifies the data source (SEC EDGAR + XBRL), the possible verdicts, the extracted structured form, and the domain limitation (v1 supports company-financial claims). No contradiction with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the query forms, states the purpose, scopes the domain, lists return values, and provides a comparative benefit—all with no unnecessary words.

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

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

Given the single parameter and no output schema, the description fully covers the tool's purpose, usage context, domain limitation, data source, return format, and efficiency gains, making it complete and informative.

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

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

The schema already provides a complete description of the 'claim' parameter with examples. The description repeats the examples but does not add new semantic details beyond the schema, justifying a baseline score of 3 for high schema coverage.

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

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

The description explicitly states the tool performs natural-language claim verification against authoritative sources, provides example queries, and distinguishes from sibling tools by mentioning it replaces multiple sequential calls.

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

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

The description clearly says 'Use whenever the agent needs to check whether something a user said is factually correct' and scopes to company-financial claims, but does not explicitly exclude non-financial claims or provide alternative tool names.

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