usgswater

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the default model is free, and that using Anthropic requires a BYO key with direct payment. It also describes the return format per-model, providing extra context beyond annotations.

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

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

The description is a single paragraph that is well-structured: main action and output, then default model, optional key, return format, and use cases. No wasted words, and every sentence adds essential information.

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

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

Given the tool's moderate complexity and 100% schema coverage, the description completely covers what the tool does, how parameters work, what the output looks like, and when to use it. No gaps are apparent.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds further meaning by stating the default model, that _apiKey is only for Anthropic, and that context helps disambiguate common names. This adds value 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's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the action (probe), resource (LLMs), and output (score). It also distinguishes itself from sibling tools like ask_pipeworx by being general and not Pipeworx-specific.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default model and when an API key is needed for Anthropic. While it doesn't explicitly list when not to use, the context is sufficient for an AI agent to decide.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context: the tool routes to many tools, returns structured answers with citation URIs, and is non-destructive. It explains what happens under the hood without contradicting annotations.

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

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

The description is front-loaded with the key instruction and packed with useful information. Every sentence serves a purpose, but it is somewhat lengthy. However, given the tool's complexity (4,774 tools, many alternatives), the length is justified and well-organized.

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

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

Given the rich annotations and no output schema, the description explains the output format (structured answer with citation URIs) and covers usage scenarios. It is comprehensive for an agent to understand how to invoke the tool correctly, though it omits details about error handling or potential rate limits.

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 each parameter. The description adds meaning by explaining that the question should be in natural language and provides examples. It also clarifies that multiple aliases (q, text, input, query, prompt) are accepted, which helps the agent understand flexibility.

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: 'Routes the question to the right one of 4,774 tools across 1242 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It provides specific verb+resource and distinguishes from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides clear when-to-use and when-not-to-use guidance: 'START HERE for most questions', 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. This gives the agent clear decision rules.

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, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral details: costs one extra LLM call, returns refusal reasons with specific values like 'not_in_source' and 'no_tool_match'. No contradiction with annotations.

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

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

Description is somewhat lengthy but front-loads the core purpose. Each sentence adds value, but could be slightly more concise without losing critical guidance.

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

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

Given the complexity (high-stakes, 28 siblings, no output schema), the description is complete: explains return format, refusal reasons, and trade-offs. Provides enough context for an agent to use it correctly.

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

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

Schema coverage is 100% with six parameters all aliased to 'question'. The description does not add semantics beyond what schema provides. Baseline 3 is appropriate as schema already documents parameters adequately.

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 distinguishes itself from the sibling 'ask_pipeworx' by noting the extra extraction step and explicit refusal mechanisms. The verb 'EXTRACTS' and resource 'answer' are specific.

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

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

Explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on...' with concrete examples. Also states preferred alternative: 'prefer ask_pipeworx for casual lookups.' This provides clear when-to and when-not-to.

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 exhaustively discloses behaviors: fan-out examples, response shapes, safety mechanisms (low-confidence short-circuits, closed markets, wide spreads), resolution-rule risk, and handling of various scenarios. This far exceeds the basic annotations (readOnlyHint, idempotentHint, etc.) and adds significant context.

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

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

The description is lengthy but justified by the tool's complexity. It front-loads the purpose and usage, and each section adds essential information. Some redundancy exists (e.g., repeating classifiers), but overall it is structured well for an AI agent.

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

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

Given the tool's complexity (multiple classifiers, fan-out, response structure, edge cases), the description is remarkably complete. It covers input, process, output fields, safety mechanisms, and interpretation hints, leaving little ambiguity. No output schema is provided, but the description compensates thoroughly.

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 with descriptions for all three parameters. The description adds extra context beyond the schema, such as examples of input formats and the effect of depth and include_raw. However, the description is not parameter-specific but still adds value.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and distinguishes from siblings like polymarket_edges by focusing on comprehensive data collection and 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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly state when not to use or list alternatives, but the context is clear enough for an AI agent.

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

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

Annotations already indicate read-only, idempotent, open world. Description adds significant behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of fiscal year offsets, sorting by primary metric, parallel call behavior, and citation URIs. No contradictions.

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

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

Description is fairly concise given the amount of useful information. It front-loads example queries and core purpose. Every sentence contributes, though it could be slightly trimmed without losing meaning.

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

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

Covers most relevant aspects: purpose, usage, data sources, behavior, output format (paired data + citations). Lacks mention of error handling for missing entities or data, but otherwise complete for a comparison tool with 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?

Schema covers 100% of parameters. Description adds value by explaining what data each 'type' retrieves (revenue/net income for companies; adverse events/approvals for drugs) and giving examples for 'values'. This enriches understanding 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 the tool does side-by-side comparison of 2-5 companies or drugs, with example queries like 'X vs Y' and 'which is bigger'. It distinguishes from sequential single-pack lookups and directly addresses common comparison intents.

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 to prefer this tool over sequential lookups for comparisons, with examples of when to use (comparing companies/drugs, ranking). Lacks explicit comparison to sibling single-entity tools like entity_profile, but covers primary use cases well.

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: account requirement, paid plan for 'thorough' depth, expected 15-60s latency, and the structure of the findings packet (verbatim evidence, gaps). No contradiction with annotations.

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

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

The description is relatively long but front-loaded with critical information (account requirement, alternative tool). Every sentence adds value; it efficiently conveys purpose, usage, and limitations without redundancy.

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

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

Given only 2 parameters, no output schema, and rich annotations, the description is complete. It covers prerequisites, expected output format, use cases, and limitations. The agent can make an informed decision solely from this 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?

Schema covers both parameters. Description adds meaning beyond schema by explaining depth values (quick=3, standard=5, thorough=8) and tying 'thorough' to paid plans. This helps the agent choose appropriate depth.

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

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

The description uses specific verbs ('decomposes', 'routes', 'returns') and clearly names the resource ('Pipeworx's 1242 STRUCTURED data sources'). It distinguishes from sibling tools like ask_pipeworx by clarifying it handles broad/multi-part questions and uses parallel tool execution.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not (breaking/current news, single lookup). Naming alternatives (ask_pipeworx) and explaining their fit provides clear guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: returns top-N relevant tools with full schemas and curated examples, ready to call directly. 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 appropriately detailed, starting with the core purpose followed by specifics. It is not overly verbose; every sentence adds information. Slightly long but justified by 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?

Even without an output schema, the description explains what the tool returns (names, descriptions, full schemas with examples) and notes limits. Covers all necessary context for an agent to use it effectively.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds value by noting alias parameters (q, task, search, description) and providing examples. Does not repeat schema but adds contextual meaning.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes from sibling tools by being the discovery mechanism.

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.' Provides examples and implies usage for browsing, searching, and discovering tools.

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

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

Description adds significant context beyond annotations: details parallel fan-out across sources, return fields (cik, filings, fundamentals, patents, news, LEI), and known issues (USPTO soft-fail). Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description enriches with operational specifics.

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

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

One dense paragraph with example queries front-loaded. Covers many details efficiently but could benefit from bullet points for returned fields. Still relatively concise given the complexity.

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

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

For a tool with no output schema, description adequately explains return structure and data sources. Mentions error handling (soft-fail for patents) and limitations (no names, company only). Sufficient for an agent to invoke correctly, though more explicit pagination details would improve completeness.

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

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

Schema coverage is 100% with good field descriptions. Tool description adds value by explaining type enum (only 'company' supported, more coming) and value format (ticker or CIK, no names) along with fallback to resolve_entity. No major gaps, but the schema itself already provides most needed info.

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 specifies verb+resource (full cross-source profile of a US public company) and distinguishes from siblings like resolve_entity by stating names not supported. Examples like 'Tell me about X' make purpose immediately understandable.

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 'ALWAYS PREFER over chaining single-pack... lookups' and contrasts with resolve_entity for name resolution. Provides example queries and states input constraints (ticker or CIK only).

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which goes beyond annotations by explaining the practical impact. No contradictions.

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

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

Two sentences, front-loaded with purpose. Every sentence adds value: purpose, usage guidance, and sibling pairing. 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?

For a simple 1-parameter tool with no output schema, the description covers purpose, usage, and relationships. Complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, with the parameter 'key' described as 'Memory key to delete.' The description mentions 'by key' but adds no further details 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?

Description starts with 'Delete a previously stored memory by key,' which clearly specifies the verb (delete), resource (memory), and method (by key). It also distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember and recall,' providing alternative tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds behavioral context beyond annotations by explaining the extraction process (fetches page, extracts title/description/key links, emits standard markdown format). It does not conflict with annotations, making it transparent and additive.

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 yet informative, with a single paragraph that front-loads the main action. Minor redundancy (e.g., 'so AI crawlers...') could be trimmed, but overall it efficiently communicates key information without being verbose.

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

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

Given the tool's low complexity (2 params, rich annotations, no output schema), the description covers the essential aspects: input, process, output format, and use cases. It could mention potential limitations (e.g., JS-rendered sites), but is otherwise complete for its purpose.

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

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

Schema coverage is 100%, and the description adds little extra meaning: for 'url' it repeats the schema's example, and for 'max_links' it restates default and max already in schema. The description does not provide new semantics that the schema lacks, thus baseline 3 is correct.

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 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource. It clearly distinguishes the tool's purpose from sibling tools like 'ai_visibility_check' which focus on different aspects of AI visibility, making the purpose unambiguous.

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

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

The description provides clear usage contexts: getting a client's site indexed, drafting for your own project, or auditing a competitor. It does not explicitly state when not to use or compare to alternatives, but the context is sufficiently clear and no sibling tool directly competes, so a 4 is appropriate.

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, idempotentHint, destructiveHint. Description adds context about what data is returned (specific fields) and that it lists active subscriptions. 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 purpose and return fields, second gives usage guidance. No wasted words.

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

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

Tool is simple with one optional parameter. Description covers return fields and usage, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with one parameter (include_inactive) already described. Description does not add further 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?

Description clearly states the tool lists the caller's active subscriptions and specifies return fields (id, type, params, etc.). It distinguishes from siblings subscribe and unsubscribe which create or cancel 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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use it relative to sibling tools.

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

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

Annotations provide readOnlyHint=false, etc., but the description adds rate limits (5 per identifier per day), cost (free, no quota impact), and that team reads digests daily. No contradictions.

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

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

The description is well-structured with purpose, usage, restrictions, and efficiency details. It is front-loaded and each sentence adds value, though slightly verbose for a feedback tool.

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

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

The description covers when, what, and how to submit feedback, including rate limits and cost. It addresses the optional context parameter indirectly. No output schema, so return behavior isn't needed.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds context (e.g., mapping type enum to scenarios) but doesn't go beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This verb+resource pairing is specific, and the tool is distinct from siblings which are query/analysis tools.

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

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

The description explicitly lists when to use this tool for bugs, features/data gaps, or praise, and advises against pasting end-user prompts. This provides clear context and excludes 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 declare read-only, idempotent, non-destructive. The description adds that data is self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This significantly enriches transparency.

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

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

The description is a single, well-structured paragraph with a clear first sentence defining the core function, followed by numbered use cases. Every sentence is informative and 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?

With no output schema, the description gives a high-level summary of return content (top tools, top packs, total call volume). It lacks detailed format, but the single optional parameter and strong annotations reduce the need for more context.

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

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

Schema coverage is 100% with one parameter fully described. The description adds meaningful context: shorter windows surface hot topics, longer windows show steady-state demand, which improves semantic 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 returns top tools, top packs, and total call volume over a recent window. It lists three specific use cases, making the purpose unambiguous and distinct from sibling tools.

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

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

The description explicitly provides three scenarios for when to use the tool. While it does not mention when not to use it or suggest alternatives, the guidance is clear and contextually sufficient given the large sibling set.

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

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

Annotations already mark the tool as readOnlyHint and idempotentHint, indicating safe read operations. The description adds rich behavioral context: it explains the monotonicity and partition-sum algorithms, the SEMANTIC ANCHOR with Jaccard similarity threshold, the PARTITION FILTER for placeholders, and the internal fill_check against live CLOB depth, including when to avoid trading. No contradiction with annotations.

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

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

The description is long but well-structured: opening sentence states purpose, followed by mode breakdown, then algorithmic details, then response format. While verbose, every sentence adds value. Minor redundancy (e.g., explaining fill_check both in-line and as a sub-process) could be trimmed, but overall information density is high and front-loaded.

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

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

Given the tool's complexity (multiple modes, algorithmic details, response structure) and lack of output schema, the description covers all necessary aspects: purpose, parameter usage, behavioral details, response format (opportunities[] fields, partition_check fields, fill_check fields), and caveats (e.g., placeholder filtering, Jaccard threshold, realizable edge). No gaps.

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

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

Schema coverage is 100% with both parameters described in the input schema. The description vastly expands meaning: it explains that passing no args triggers trending_scan, provides examples for event slugs ('fed-decision-may-2026'), accepts full URLs, and describes how topic mode searches related events. It also clarifies that the tool has three distinct modes based on parameter presence.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_fill_risk by explicit mention ('For custom sizing use polymarket_fill_risk'), and the detailed mode explanations (trending_scan, event, topic) clarify the specific use cases.

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

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

The description provides explicit when-to-use guidance for each parameter: no args for trending_scan, 'event' for a specific market slug, 'topic' for cross-event scanning. It recommends event mode for specific markets and explains that cross-event mode catches patterns missed by single-event. It also warns when not to trade based on fill_check results, giving clear decision criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds substantial behavioral context: caching at KV level keyed on all knobs (1h), Fed bets surfaced but excluded from ranking, diagnostic output revealing why segments are empty, and details on each model family's calculations (e.g., lognormal barrier, GDELT ratio, partition_overround with sport-specific α). No contradictions.

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

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

The description is well-structured with clear segments and bullet-like details. It front-loads the purpose and key segments. However, it is somewhat dense and could be more concise without losing information; a few sentences could be shortened.

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 9 parameters, no output schema, and complex behavior, the description is exceptionally complete. It explains the output structure (by_segment, fed_candidates, diagnostics), caching, knob effects, and even model formulas. The annotations cover safety. An agent can fully understand when and how to invoke this tool.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds useful context beyond schema, such as the rationale for min_kelly (skip too-small opportunities), explanation of slippage_pp (20-50bp typical in Polymarket), and why min_partition_leg_kelly is needed (partition arbs have zero parent-level Kelly). This adds meaningful value.

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

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

The description clearly states the verb 'scan' and the resource 'top Polymarket markets', and explains the core value: returning opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on cross-data disagreement and daily 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 states 'Built for "what should I bet on today"' and explains when to use tradeable-edge knobs (min_liquidity, max_spread_pp). It describes the three segments and their typical use cases. However, it does not explicitly compare to siblings or state when not 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?

The description adds rich behavioral context beyond annotations: explains history depth bounded by 60-day TTL, snapshot gaps due to cache-miss, decay computed from daily closes (not intraday), and the meaning of negative edge values. All annotations are consistent and supplemented.

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

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

The description is front-loaded with the core purpose and then provides detailed response structure and limits. It is dense but not excessively verbose; could benefit from bullet points for clarity but remains acceptable for 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 no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) with field meanings and caveats (decay values, lifespan, gaps). It covers usage limits and edge cases, making it self-contained for correct invocation.

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

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

Schema coverage is 100% so baseline is 3. The description adds minor context (window default '1wk', snapshot family concept) but does not significantly extend semantic understanding beyond the schema parameter descriptions.

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

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

The description clearly states it provides telemetry on edge persistence and decay from daily snapshots, answering a specific question about edge age versus freshness. It distinguishes from the sibling 'polymarket_edges' by focusing on historical tracking rather than current snapshots.

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

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

The description implies when to use this tool (for historical edge behavior) versus alternatives by referencing 'fresh wide edge' vs '3-week-old edge'. However, it does not explicitly exclude other tools or provide direct comparison to similar siblings like 'polymarket_edges'.

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, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: it walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, etc., and explains basket-mode risks such as thin legs and forced directional risk. There is no contradiction with annotations.

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

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

The description is long but well-structured with clear sections for requirements, single-market mode, basket mode, and usage guidance. It front-loads the core purpose and required parameters. Some redundancy could be trimmed, but the length is justified by the complexity of the tool. It earns 4 for compactness given the content density.

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

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

Despite the absence of an output schema, the description fully documents all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and explains basket-specific outputs like capture_ratio, profit_usd, thin_legs, and forced_directional_risk. The description is complete for the tool's intended use.

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

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

Schema description coverage is 100% with all 4 parameters described, but the description adds further meaning: default values (side default buy_yes for single-market, auto for basket), interpretation of size_usd (max spend on buys, target proceeds on sells for single-market; settlement notional for basket), and clamp range (10–1,000,000). This goes beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and the verb 'check' combined with 'fill risk' makes the action clear. Sibling tools like polymarket_arbitrage and polymarket_edges are differentiated by the description's focus on pre-trade risk assessment.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the risks of not using it (theoretical overround not capturable, partial basket fills leading to unhedged positions), giving clear context for decision-making.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds extensive behavioral details: response structure, compatibility_warning conditions, temporal_alignment, skipped counters. 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?

Well-structured with sections (modes, response, safety fields). Length is justified by complexity, but could tighten some phrases. Front-loaded with core 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?

No output schema, so description fully explains return values (leg-by-leg prices, matched spread, safety fields with detailed conditions). Covers all necessary context for tool 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 coverage is 100% with descriptions. Description adds context beyond schema (topic auto-fetches events, explicit tickers override topic). Slight redundancy but overall adds value.

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

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

Clear verb ('cross-venue spread') and resource ('between Kalshi and Polymarket for the same resolving question'). Distinguishes from siblings like polymarket_arbitrage by focusing on spread across two venues.

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 describes two modes (topic shortcuts vs explicit tickers) and when each is appropriate. Warns that pre-mapped topics often return compatibility warnings, setting clear expectations.

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

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

Adds scoping per identifier and behavior for omitting key, which supplements 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?

Three sentences, front-loaded with action, no wasted words. Efficient and clear.

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

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

Given one optional parameter and no output schema, the description covers both usage modes, scoping, and pairing, which is complete for this tool.

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

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

Schema covers 100% with clear description; description reinforces and adds examples, adding slight value over schema.

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

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

The description clearly states the tool retrieves saved values or lists keys, with specific verb and resource. It distinguishes from siblings remember and forget.

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

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

Explicitly tells when to use (look up stored context) and pairing with remember/forget. No when-not stated, but alternatives are 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 a mutation via mark_read:true (flags events as read), which contradicts the readOnlyHint:true annotation. This is a serious inconsistency, reducing transparency despite other useful behavioral details.

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

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

Four sentences, front-loaded with purpose, each sentence adds value (purpose, return content, filtering, polling/alternatives). No redundant 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?

Covers return structure, filtering, and side effects. Could explicitly mention 'limit' and 'unread_only' parameters, but schema covers them. Good overall.

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 meaningful context for 'type', 'since', and 'mark_read' beyond schema descriptions, enhancing 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 it pulls fired events from the subscription feed, specifying the content (source, citation_uri, raw event payload). It distinguishes from siblings like list_subscriptions by focusing on events rather than 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 provides clear context for when to use this tool (retrieve recent alerts) and mentions polling works fine. It also offers an alternative HTTP endpoint for scripts/dashboards, but does not explicitly exclude alternatives or give when-not-to scenarios.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO with sunset note. It does not contradict annotations.

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

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

The description is moderately lengthy but every sentence adds value. It front-loads the purpose with examples. Could be slightly more concise, but no wasted content.

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

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

Given no output schema, the description mentions the return structure (changes[], total_changes, citation URIs). It also covers fallback behavior and API sunset. Complete for the tool's complexity.

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

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

Schema coverage is 100%. The description adds examples for 'since' (ISO date vs relative shorthand like '30d'), clarifies 'value' accepts ticker or CIK, and confirms 'type' only supports 'company'. This adds meaning beyond the schema.

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

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

The description clearly states the tool returns a change feed for a company within a time window, with many example queries. It distinguishes from the sibling tool 'entity_profile' by noting that tool is for static profiles.

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 provides example queries for when to use this tool and directs users to use 'entity_profile' for static profiles. It also gives guidance on the 'since' parameter format.

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

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

Adds context beyond annotations: scope by identifier, persistence for authenticated vs anonymous users. No contradiction with annotations (idempotentHint=true, readOnlyHint=false).

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

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

Three concise sentences that front-load purpose and include necessary context. No wasted words.

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

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

For a simple key-value tool with 2 parameters and no output schema, the description covers purpose, usage, persistence, and sibling tools 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% with clear descriptions. The description adds naming examples (e.g., 'target_ticker') which provide extra guidance beyond the schema.

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

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

The description clearly states it saves data for reuse later across conversations or sessions. It uses specific verbs ('Save') and distinguishes from sibling tools like recall and forget by mentioning 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?

It explicitly says when to use ('when you discover something worth carrying forward') and mentions companion tools (recall, forget). However, it does not explicitly list 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that each call cascades through several endpoints, replacing 2-3 manual lookups, providing useful behavioral insight 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?

Front-loaded with example queries, each sentence adds value. Efficiently covers purpose, usage, supported types, and internal behavior in a compact format.

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?

Explains return values per type and internal cascading. Lacks mention of error conditions or limits, but given no output schema, it provides enough context for agent invocation.

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

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

Schema coverage is 100% with both parameters described. Description adds examples and mentions auto-disambiguation for company type, but doesn't substantially extend 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 resolves names to canonical IDs, with specific examples (ticker, CIK, RxCUI). It distinguishes from siblings by positioning itself as the first step when an ID is needed.

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 to 'Use FIRST whenever you have a name but need an ID.' No explicit when-not or alternatives, but the sibling list lacks a direct substitute, making the guidance sufficient.

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

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

Annotations already declare it read-only, idempotent, and non-destructive. The description adds that it internally probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This provides behavioral insight 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 4 sentences, each delivering essential information: purpose, method, use case, and output. It is front-loaded and free of unnecessary words. Highly concise.

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

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

Given the tool's complexity (4 params, no output schema), the description covers input entities, optional parameters, internal call to ai_visibility_check, and output format (ranked list with score, confidence, signal density). It also explains the relationship to a sibling tool. This is sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by noting that the first entity in the entities array is treated as the 'subject' for narrative, which is not in the schema description. It also reiterates the 2-8 limit and that models are optional. This additional detail justifies a 4.

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

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

The description clearly states it compares AI visibility across entities side-by-side, specifically probing each with ai_visibility_check and ranking by score. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI visibility audits. The use case example reinforces its purpose.

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

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

The description provides a clear use case (competitive AI-marketing audits) and implies it is for comparing multiple entities at once. However, it does not explicitly exclude alternatives or mention when to use a simpler tool like ai_visibility_check for a single entity. The context is clear but lacks explicit when-not guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds critical behavioral details: it fans out across multiple sources, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. This fully informs the agent of runtime 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 somewhat lengthy but well-structured, front-loading the core purpose. Every sentence adds value, though it could be slightly more concise. The compound sentence at the start is effective.

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

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

Given the tool's complexity (multiple external APIs, partial failures, no output schema), the description covers all essential aspects: what's returned (summary, advisories, links, alternatives), how failures are handled, and timing constraints. It is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100% with good descriptions for both parameters. The description adds value by explaining defaults (version defaults to latest) and output structure (summary block, etc.), which indirectly clarifies parameter usage. However, the parameter descriptions themselves are already clear, so minimal additional insight.

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's a composite check for adding an npm package, using specific verbs like 'scan' and 'check'. It distinguishes from other tools by mentioning the combination of deps.dev and bundlephobia, and it's different from sibling tools like 'entity_profile' or 'bet_research'.

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

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

Explicitly tells when to use: for questions about safety, popularity, size, or cost of adding a package. It also notes limitations (NPM only in v1) and suggests alternatives (deps.dev:version for other ecosystems), providing clear usage 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context beyond annotations: mentions embeddings model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars with truncation flag), and return format (passages with offsets and scores). 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 somewhat long but every sentence adds information. It is well-structured with clear sections: purpose, when to use, pairing with sibling tool, and technical details. Could be slightly more concise, but the information density justifies the length.

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

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

Despite lacking an output schema, the description fully specifies the return values: 'top-N passages with character offsets and similarity scores'. It also explains truncation behavior for long inputs. For a tool with 3 parameters and no nested objects, this is complete and leaves no ambiguity.

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

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

Schema description coverage is 100% (all parameters have descriptions). The description adds value by providing examples for query ('supply-chain risk', 'fiscal year 2024 revenue') and clarifying the max character limit for text. This goes beyond the schema but does not fully re-document each parameter.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using verbs like 'search inside' and specifying the resource as 'a fetched record'. It distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded and is used when the record is too large for the prompt.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Also provides clear alternatives by mentioning 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This guides the agent on proper invocation 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 indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds important behavioral details not in annotations: OAuth requirement, delivery caps, webhook auto-disable after 10 failures, one-time secret. No contradiction with annotations.

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

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

Description is long but every sentence adds value. Front-loaded with purpose and returns ID. Well-structured by breaking into types, delivery channels, and constraints. Could be slightly more concise, but structurally sound.

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 essential aspects: types, parameters, delivery options, constraints, prerequisites (OAuth, phone verification). No output schema, but description mentions return of subscription ID. Could include more on response structure, but sufficient for a creation tool.

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

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

Schema coverage is 100%, and description provides rich additional meaning: concrete examples for each type, parameter constraints (e.g., E.164 format, verification requirement), conditional requirements (sponsor or condition for clinical_trial). This far exceeds 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?

Clearly states the verb 'create', the resource 'proactive monitoring subscription', and the outcome 'returns subscription id'. Distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 extensive context: requires Pipeworx OAuth account, anonymous/BYO cannot persist, lists supported types with examples, delivery options with constraints (SMS cap, phone verification). Does not explicitly say when not to use, but the context is thorough enough to guide appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns example questions 'drawn from the live catalog of thousands of tools' and that calling with no arguments gives the full spread, enhancing transparency about behavior and output scope.

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

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

The description is well-structured with a leading list of example queries, but is slightly verbose (e.g., listing all categories in parentheses). Every sentence serves a purpose, but could be trimmed slightly without losing clarity.

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 (1 optional parameter, no output schema), the description is comprehensive: it explains the tool's role, when to use, what the output contains, relationship to sibling tools, and parameter behavior. No gaps remain for an AI agent to understand 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 has 100% coverage with a description for the single 'topic' parameter. The description adds a list of possible values ('finance | pharma | economics | ...') and explains the effect of omitting vs. passing a topic, providing meaning beyond the schema's basic 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 is the onboarding entry point for an agent to learn what Pipeworx can do, returning category-bucketed example questions with exact tool+argument shapes. It specifies the resource ('example questions') and verb ('suggest_questions'), and distinguishes from siblings by positioning it as the first tool to use when unfamiliar with Pipeworx.

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

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

Explicitly tells when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides alternatives like 'ask_pipeworx, entity_profile, compare_entities' and explains parameter usage (omit for full spread, pass topic to focus).

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?

Disclosure of ownership enforcement and deactivation (not deletion) adds valuable context beyond annotations. Aligns with idempotentHint=true and destructiveHint=false.

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 purpose, no extraneous content.

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

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

Simple tool with one param and clear annotations. Description covers ownership, behavior, and persistence of historical data. No output schema needed.

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?

Parameter 'id' fully described in schema with coverage 100%. Description adds useful context ('returned by subscribe').

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

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

Explicitly states 'Cancel a subscription by id', with clear verb and resource. 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?

States ownership enforcement and non-destructive deactivation. Provides context for when to use, though no explicit alternatives mentioned.

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 context beyond annotations: it specifies supported claim types (company-financial), data sources (SEC EDGAR + XBRL), version (v1), and return structure (verdict, structured form, actual value with citation, percent delta). This fully discloses behavior and limitations.

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 somewhat verbose but well-structured: it starts with purpose and examples, then specifies domain and return details. Each sentence adds value, but it could be slightly more concise without losing clarity.

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, high schema coverage, and absence of output schema, the description fully covers what the tool does, how it works, and what it returns. No apparent 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?

With 100% schema coverage, the baseline is 3. The description adds value by providing example claims and clarifying the natural-language nature, though it does not elaborate further on parameter syntax or constraints 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 the tool as a natural-language claim verifier with specific examples like 'fact check' and 'verify the claim'. It distinguishes itself from siblings by mentioning it replaces multiple sequential calls, and specifies the domain of company-financial claims.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides domain constraints. However, it does not mention when to use alternative tools or exclude inappropriate scenarios.

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