Datos Ar

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds crucial context: default model is free, _apiKey is passed directly to Anthropic (BYO cost), and output structure includes per-model fields plus 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?

Single paragraph of four sentences, front-loaded with main action, then details on models, cost, and output. Every sentence adds distinct information without redundancy or verbosity.

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

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

No output schema, but description explicitly states return format (per-model {score, confidence, signals, raw_response} + combined view). Covers all aspects: purpose, parameters, output, and use cases. No gaps given tool 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?

Input schema covers 100% of parameters with descriptions. Description adds value by specifying default model (Workers AI Llama-3.3-70b free), explaining _apiKey necessity, and contextualizing 'context' parameter for disambiguation. Enhances schema 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?

Description clearly states the tool 'probes LLMs for what they know about a business/brand/product/topic and scores visibility (0-100) per model', which is a specific verb+resource. It distinguishes from siblings like 'scan_competitor_ai_presence' by being general-purpose rather than competitor-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?

Description provides usage context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the _apiKey for Anthropic. However, it does not explicitly state when to use this tool vs. specific siblings, leaving some ambiguity.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable detail: routes questions to sub-tools, fills arguments, returns structured answers with pipeworx:// citation URIs. This explains the meta-behavior 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?

The description is somewhat long but well-structured: starts with key guidance, lists categories, describes routing, gives usage triggers, and ends with examples. Every sentence provides useful information. Could trim slightly, 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?

Given the tool's complexity (meta-tool routing to many sources) and lack of output schema, the description covers purpose, usage, behavior, and examples. It explains the citation URIs. Missing details on error handling or response format, but these are secondary given the thoroughness.

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 6 parameters (all aliases) with 100% coverage. Description adds context: examples of valid questions ('current US unemployment rate', 'Apple's latest 10-K') and notes that natural language is accepted. This meaningfully extends the schema's documentation.

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 for asking questions about current/historical data from over 3,744 tools and 884 sources. It lists specific domains (SEC filings, FDA, FRED, etc.) and contrasts with web search. It implicitly distinguishes from siblings like 'ask_pipeworx_grounded' by emphasizing its routing capability.

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 over web search for factual questions and lists trigger phrases like 'what is', 'look up', 'find'. Includes examples. However, it does not explicitly exclude use cases or contrast with specific sibling tools (e.g., when to use 'ask_pipeworx_grounded' instead).

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds detailed behavioral context: it routes to the correct tool, fills arguments, fetches data, extracts answers exclusively from tool results, and returns explicit refusal reasons. No contradiction with annotations.

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

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

The description is well-structured and front-loaded, but somewhat lengthy. Every sentence adds value, providing purpose, process, output format, and usage guidance. Minor room for trimming.

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

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

Despite no output schema, the description fully explains return values (answer, evidence, confidence, source, etc.) and failure modes (refusal reasons). For a tool with multiple aliased parameters and a complex process, this is comprehensive.

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, all aliases for 'question'. Description does not add parameter details beyond stating it accepts natural language, but the schema already provides sufficient documentation. Baseline 3 appropriate.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the verb 'extracts the answer using ONLY what the tool result contains', distinguishing it from the sibling 'ask_pipeworx' for casual 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?

Explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also advises preferring 'ask_pipeworx' for casual lookups, providing a clear when-not criterion.

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. The description adds extensive behavioral details: resolver confidence, safety short-circuits, closed market handling, wide-spread liquidity warnings, resolution-rule risk, and news fallback behavior. 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 comprehensive but quite verbose (multiple paragraphs). It front-loads the purpose but includes many details that could be organized better. Every sentence adds value, but it exceeds ideal conciseness for quick agent comprehension.

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

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

Given no output schema, the description thoroughly explains response shapes (market, analysis, evidence), edge cases (low confidence, closed markets), resolution rules, and safety mechanisms. It is extremely complete for a complex tool with many sub-features.

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 some context (e.g., market can be slug, URL, or question; depth default thorough; include_raw effect on response size) but the schema already provides good descriptions. No significant extra 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 starts with a clear verb+resource: 'Research a Polymarket bet'. It explicitly distinguishes from siblings by focusing on Pipeworx data for Polymarket bets, which is unique among 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 states explicit use cases ('Use for "should I bet on X"...') and implies alternatives through sibling context (e.g., `ask_pipeworx` for general queries). However, it does not explicitly state when not to use the tool.

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

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

The description details data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinicaltrials for drugs), handles off-calendar fiscal years, explains sorting by primary metric, and mentions citation URIs. This goes well beyond the annotations (readOnlyHint, idempotentHint, etc.).

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 well-structured and front-loaded with the core purpose and usage guideline. Each sentence adds value, though some examples could be slightly condensed. Overall, it's appropriately sized for 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 lacking an output schema, the description adequately explains return values (paired data + citation URIs) and sorting behavior. It covers both entity types and edge cases (off-calendar fiscal years), providing sufficient context for correct invocation and interpretation.

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

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

The description adds rich context about the meaning of each type and values: 'type="company" pulls LATEST 10-K revenue + net income + cash + long-term debt from SEC EDGAR/XBRL' and 'type="drug" pulls FAERS adverse-event counts, FDA approval counts, active trial counts.' This significantly enhances the minimal 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 specifies the action (side-by-side comparison), the resource (companies or drugs), and the count (2-5). It explicitly contrasts with sequential single-entity lookups, differentiating from sibling tools like entity_profile or resolve_entity.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This clearly states when to use this tool and implies when not to (for single entities).

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

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint true. Description adds return format (structured findings packet with evidence, confidence, source, citations, gaps), behavior (never invents, extracts verbatim), and time expectation. 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?

Description is around 120 words, front-loaded with key value, and each sentence adds information. Could be slightly more concise but still 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?

Given complexity and no output schema, the description covers what the tool returns (findings packet with evidence, gaps), prerequisites, time cost, and use cases. Thorough enough for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, but description adds meaningful context: depth values map to number of facets (quick=3, standard=5, thorough=8) and clarifies default. For question, it emphasizes broad/multi-part is fine. Adds value beyond schema.

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

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

The description states 'Grounded multi-source research in ONE call' and explains the decomposition and parallel routing to 3,744 tools. It clearly distinguishes from sibling tools like ask_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 states 'Use for broad or multi-part questions' and contrasts with ask_pipeworx for single lookups. Also mentions prerequisites (Pipeworx account, paid plan for thorough) and expected time.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call. No contradictions.

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

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

Description is slightly long but effective, front-loaded with purpose. Every sentence adds value. Could be more concise but not wasteful.

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 explains return format. Covers usage, examples, and constraints. Complete for a discovery tool with multiple aliases.

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 detailed descriptions. Description adds examples and explains aliases for query, providing context beyond schema.

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

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

The description clearly states it finds tools by describing data or task, listing many domains. It distinguishes itself from siblings (e.g., get_series, entity_profile) which are specific tools, not 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 says 'Call this FIRST when you have many tools' and 'use when you need to browse, search, look up, or discover what tools exist.' No when-not-to-use, but clear context.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds valuable details: patent soft-fail, news fallback, exact return fields. 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?

Long but front-loaded with examples and directive; every sentence adds value. Efficiently packs complex 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?

Thoroughly describes all sources, return fields (with specifics like up to 5 filings, URIs, sorted fundamentals), and caveats. 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?

Schema descriptions cover 100% of parameters. Description adds context: type enum is currently only 'company' and value accepts ticker or zero-padded CIK but not names.

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 example queries, explicitly states it provides 'full cross-source profile of a US public company in ONE parallel call,' and distinguishes from sibling tools like resolve_entity 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 says 'ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view' and warns that names are not supported, directing to use resolve_entity first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description's 'Delete' is consistent. However, the description adds no behavioral context beyond the annotations, resulting in a baseline score.

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 the action, second provides usage guidance. No wasted words; information is front-loaded and efficient.

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

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

For a simple tool with one parameter, complete annotations, and no output schema, the description fully covers purpose and usage, making it sufficient for the agent.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The tool description adds no additional meaning beyond what the schema provides, so baseline score is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', providing a specific verb (Delete) and resource (memory by key), and distinguishes from sibling tools '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') and recommends pairing with 'remember' and 'recall', offering 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description supplements by explaining the internal process (fetches page, extracts data, emits markdown) and output format, 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?

The description is concise and front-loaded with the main purpose. Each sentence serves a clear function 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 simplicity of the tool and high schema coverage, the description provides sufficient context about output format and usage. No output schema exists, but the description explains what the tool returns.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by specifying the default and maximum for max_links and clarifying the output format, which is not covered by 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 generates a production-ready llms.txt file for any URL, with a specific verb and resource. It distinguishes itself from sibling tools that are unrelated.

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 lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. It does not mention when not to use or alternatives, but the contexts 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context about the data being official Argentine statistics and titles in Spanish, and describes the return format as rows of date, value, plus metadata. 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?

Five concise sentences with no wasted words. Front-loads the main purpose and key features. Each 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 8 parameters, no output schema, and 1 required param, the description covers core functionality, multiple ids, collapse, representation_mode, and return format. Minor gaps like limit and metadata are covered in schema, so overall 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% but the description adds valuable meaning: comma-separated ids for alignment, examples for collapse (e.g., monthly→yearly avg) and representation_mode (percent change vs a year ago). This goes beyond the schema enum labels.

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 fetches observations for Argentine time series by id. It specifies the verb 'Fetch', the resource 'observations for one or more Argentine time series', and distinguishes from search_series by noting ids come from that tool.

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

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

It explains when to use the tool (after search_series) and how to use multiple ids for alignment. It does not explicitly state when not to use it, but the context of data source and language provides clear usage guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the specific fields returned and the usage context, which enhances transparency 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?

The description is two sentences with no fluff, front-loaded with the core function, and then usage guidance. 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?

For a simple read-only list tool with one optional parameter, the description covers purpose, return fields, and usage guidance. Sibling tools exist but differentiation is clear. No output schema, but fields are listed. 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 the parameter include_inactive is already fully described. The description does not add any additional meaning or syntax for the parameter, thus meets the baseline.

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

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

The description clearly states it lists the caller's active subscriptions and enumerates the fields returned. It distinguishes itself from sibling tools like subscribe and unsubscribe by specifying the purpose of reviewing or finding an id to cancel.

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: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context but does not explicitly mention when not to use it, though the use cases are well-covered.

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: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that the team reads digests daily. Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description enriches the agent's understanding.

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

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

The description is well-structured with clear categorization and important constraints. It is slightly verbose but front-loads the purpose. Every sentence adds value, though it could be a bit more compact.

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 feedback tool, the description covers all necessary aspects: purpose, use cases, constraints, and best practices. No output schema is needed for this tool, so completeness is high.

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

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

Schema description coverage is 100% for all three parameters. The description reinforces the meaning of type, context, and message, but does not add substantial new semantics beyond what the schema already provides. A score of 3 is appropriate as the baseline.

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

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

The description clearly states the tool is for sending feedback (bugs, features, praise) to the Pipeworx team. It uses specific verbs and resources, and distinguishes itself from sibling tools which are mostly data retrieval or 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 the tool (bug, feature, data_gap, praise) and provides guidance on what not to include (don't paste end-user prompt). It also mentions rate limits and that it's free. However, it does not mention alternative tools for feedback, as this is the only feedback 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 fully discloses the aggregated and privacy-safe nature ('no PII'), data source ('CF analytics-engine'), caching behavior ('5min-1h'), and self-aggregating signal, all beyond what annotations provide.

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

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

The description is a focused paragraph with front-loaded purpose, structured list of use cases, and no extraneous information; every sentence earns its place.

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

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

Given no output schema, the description adequately explains return values and data freshness. For a simple read-only tool with one optional parameter, this 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?

The lone parameter 'window' has 100% schema coverage and the description adds practical guidance on interpretation ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enhancing the enum values.

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' for a given window, distinguishing it from siblings like discover_tools or get_series by focusing on trending usage rather than content retrieval.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, aligning use case), but no explicit when-not-to-use or alternative tools are mentioned, though the context makes alternatives 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?

Adds extensive behavioral details beyond annotations: computation of partition_check, fill check against live CLOB depth, semantic anchor (Jaccard similarity threshold), partition filter for placeholders, and condition for 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?

Somewhat lengthy but every sentence adds value. Front-loaded with the requirement. Slightly verbose but justified given tool 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?

Thorough explanation of return structure (opportunities array, partition_check object) and edge cases like fill check and placeholders. Adequate for a 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?

Even with 100% schema coverage, description significantly enhances parameter meaning by explaining the two modes, providing example values (event slug, topic seed question), and describing expected behavior for each.

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

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

Clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes from sibling tools like polymarket_fill_risk by mentioning it 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 recommends event mode for specific markets and topic mode for cross-event scanning. Warns that calling with no args fails and directs to polymarket_fill_risk for custom sizing, providing clear when-to-use 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?

The description goes far beyond the annotations (readOnlyHint, etc.) to explain detailed behavior: three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with mathematical formulas (lognormal barrier, GDELT ratio, partition_overround with per-sport α, etc.), caching at 1h, diagnostics field, and handling of Fed bets. 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 front-loaded with the core purpose in the first sentence. However, it is quite long and dense. Every sentence adds value given the complexity (3 model families, detailed knobs), but it could be more concise by grouping or simplifying some technical details. Still, it does not waste words.

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

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

The description is extremely comprehensive for a tool with 9 parameters and no output schema. It covers all three segments, tradeable-edge knobs, response structure (including diagnostics and fed_note), caching, and even edge cases like placeholder filters. An agent could invoke this tool correctly with just 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?

With 100% schema coverage, the baseline is 3, but the description adds significant value beyond the schema. For example, it explains why default slippage is 0.3 (zero fees but bid/ask depth), how min_kelly filters single-leg vs partition opportunities, and what min_partition_leg_kelly does (since partition arbs have zero parent-level Kelly). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses specific verbs like 'scan' and 'return' and identifies the resource (Polymarket markets). The sibling tools (e.g., polymarket_arbitrage, bet_research) are different enough that this description distinguishes itself by focusing on Pipeworx data disagreement.

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 the use case: 'what should I bet on today' and that agents discover opportunities without paging hundreds of markets. It provides guidance on when to use tradeable-edge knobs (min_liquidity, max_spread_pp). However, it does not explicitly contrast with siblings or state when not to use this tool, which would elevate it to a 5.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds rich detail: snapshot dependency on cache-misses, daily close computation, bounded history, and specific output structure (tracked, expired, snapshot_dates). Exceeds annotation requirement.

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 dense but well-organized: purpose first, then response structure, then limitations. Every sentence adds value, though could be slightly more compact.

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 (tracked[], expired[], snapshot_dates[]) with fields. Covers limitations (TTL, daily closes, gaps). Complete for a tool with 2 optional params.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context by explaining the lookback and snapshot family impact, plus limitations like 60-day TTL and gaps. Provides value beyond schema.

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

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

Description specifies 'edge persistence and decay telemetry' and answers a clear question about edge age and shrinkage. Distinguishes from sibling `polymarket_edges` by focusing on time-series behavior.

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?

Implicitly advises when to use by contrasting fresh vs. old edges, suggesting it's for assessing edge quality over time. Does not explicitly exclude other use cases or name alternatives, but context is clear.

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

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

Annotations indicate it is read-only, idempotent, and non-destructive. The description adds significant behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about risks like partial basket fills converting arbs into unhedged positions. No contradiction with annotations.

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

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

The description is dense but well-structured with bold/caps for emphasis. It is somewhat lengthy, but every sentence adds value given the tool's complexity. Could be slightly more concise, but overall adequately sized and front-loaded with 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?

Given the tool complexity (no output schema, 4 parameters), the description covers all essentials: purpose, modes, parameter details, return fields, usage guidance, and potential risks. It is complete enough for an AI 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 description coverage is 100% (all 4 parameters described). The description adds meaning beyond schema: explains the dual interpretation of 'side' (single-market vs basket default auto), clarifies 'size_usd' in both modes (spend/target vs settlement notional), and provides defaults and clamps.

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 specifies the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating its use 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 gives explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about theoretical overround on thin books and partial basket fills, providing clear context for when to use the tool.

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

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

The description provides extensive behavioral context beyond annotations: explains safety fields like compatibility_warning, temporal_alignment, skipped_cross_type/subtype, and conditions when spreads are meaningless. No contradiction with readOnlyHint and idempotentHint.

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

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

The description is relatively long but every sentence adds value, covering modes, response structure, safety fields, and caveats. It is front-loaded with purpose. Could be slightly tighter, but appropriate for the complexity.

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

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

Despite no output schema, the description thoroughly explains the response format (leg-by-leg prices, spread array, safety fields) and the meaning of each field. It covers all necessary aspects for a tool with two modes and complex safety conditions.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaning by explaining the two modes and how topic overrides explicit parameters, plus listing macro-shortcut values. This adds value 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on multi-venue 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 describes two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings, advising when spreads are not meaningful. However, it does not explicitly name alternative tools for single-venue or other analyses.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds crucial context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' This explains the tool's behavior beyond annotations, with no contradictions.

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

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

The description is two sentences, each serving a distinct purpose: stating the core function and providing usage context. It is front-loaded and concise with no extraneous 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 retrieval tool with no output schema, the description fully specifies behavior: retrieving by key or listing all keys, and clarifies scope. It is complete for the tool's 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% with a detailed description of the 'key' parameter. The description rephrases the same information ('omit the key argument' corresponds to listing keys) but adds no new semantic value beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb (retrieve/list) and distinguishes itself from siblings like '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?

The description explicitly says 'Use to look up context the agent stored earlier' and provides examples (ticker, address, research notes). It also advises pairing with 'remember' and 'forget', offering clear guidance on when and how to use the tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral detail: mark_read:true flags returned events as read, affecting subsequent calls. No contradictions.

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

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

Four sentences, each serving a clear purpose: core function, returned fields, filtering, and additional usage tip. No fluff, well 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 has no required params and no output schema, the description covers what the tool returns, how mark_read works, and mentions an alternative access method. Annotations handle safety. Complete for the complexity.

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

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

Schema coverage is 100%, but description adds concrete examples ('sec_8k' for type, ISO timestamp for since) and explains mark_read's effect on next call, going 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 pulls fired events from the subscription feed, specifying returned fields (source, citation_uri, payload) and filtering options. This distinguishes it from sibling tools like list_subscriptions or subscribe.

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 usage context: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This hints at when to use this tool vs. the direct API, but doesn't explicitly state when not to use.

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

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

Beyond annotations (readOnlyHint, etc.), the description details fan-out to multiple sources, fallback behavior, soft-fail for USPTO, return structure with citation URIs, and accepted formats for 'since'. 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 comprehensive and front-loaded with examples, but slightly lengthy. However, every sentence adds value, so it earns a 4 for efficient communication.

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 data sources, fallback logic, soft-fail), the description fully explains behavior, return format, and provides an alternative tool reference. No output schema, but the description compensates.

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 reinforces the 'since' format with examples but does not add significant new meaning beyond the schema's 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 returns a change feed for a company over a recent time window, with example queries. It distinguishes itself from the sibling tool entity_profile by specifying 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?

The description explicitly instructs to use entity_profile instead for static profiles, providing clear when-to-use vs when-not-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?

The description adds significant behavioral context beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour for anonymous sessions. Annotations already indicate idempotentHint=true, and description aligns without contradiction.

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

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

The description is concise (4 sentences) and front-loaded with the primary purpose. Every sentence adds value: use case, scoping, persistence, and pairing with sibling tools.

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), the description is fully complete. It covers purpose, usage, behavior (scoping, persistence), and related tools, leaving 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%, but the description provides example key formats (e.g., 'subject_property', 'target_ticker') and clarifies that the value can hold any text, adding practical meaning beyond the schema's generic 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: 'Save data the agent will need to reuse later'. It specifies the verb 'save', resource 'data', and distinguishes from sibling tools like recall and forget.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions complementary tools recall and forget, offering clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it cascades through multiple lookup endpoints internally, replacing 2-3 manual lookups, and details output as 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?

Well-structured with front-loaded query examples and clear separation of supported types. Some length but every sentence adds value; could be slightly more concise.

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

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

Despite lacking an output schema, the description details return values per entity type, including citation URIs. Does not cover error handling or pagination, but sufficient 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 covers both parameters with 100% coverage. Description adds meaning by specifying return fields per type (ticker, CIK, company name for 'company'; RxCUI, ingredient, brand for 'drug') and notes 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 specifies the tool resolves user-spoken names to canonical identifiers, with clear examples like 'ticker for...' and 'find the CIK for...'. It distinguishes from siblings by being the sole entity resolution tool among a diverse set of search, research, and feedback 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 FIRST whenever you have a name but need an ID' and lists supported types (company, drug) with detailed input/output. Does not explicitly say when not to use, but the context is clear and 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 indicate a read-only, idempotent, open-world tool. The description adds that it internally calls ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond annotations and provides a clear behavioral outline.

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, well-structured: first sentence states core function, second describes mechanism and output, third provides use case. 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?

Given no output schema, the description adequately notes output format (ranked list with score, confidence, signal density). It also mentions internal probe call. With 4 params fully documented in schema, the description is fairly complete, though lacks details like rate limits or authorization nuances (which are partially covered in schema with _apiKey).

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

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

Schema coverage is 100%, but the description adds meaningful context: entities first entry is treated as 'subject' for narrative, rest are competitors. This supplements the schema which only describes it as an array. Other parameters are adequately described in schema and description does not add much beyond.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using probes with ai_visibility_check, ranking by score, and surfacing the most/least recognized. It is distinct from siblings like ai_visibility_check (single entity) and compare_entities (general 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 provides a use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use this tool or directly compare against alternatives like ai_visibility_check for single entities.

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

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

Annotations already indicate safe, non-destructive operation. Description adds important behavioral details: bundlephobia first measurement can take 5-30s, sources_failed will list timeouts, graceful degradation.

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: purpose first, then usage, return info, limitations, and fallback behavior. Every sentence adds value, no fluff.

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

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

Despite no output schema, description fully explains return format: summary block, per-advisory detail, links, alternative versions, and failure handling. Covers complexity comprehensively.

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 adequate descriptions. Description adds useful context: scoped packages accepted, version defaults to latest. This enhances 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 it's a composite check for npm packages using deps.dev and bundlephobia, with specific outputs. It distinguishes from sibling tools by being unique in functionality.

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 (e.g., 'is X safe / popular / small') and when not to (NPM only, other ecosystems fall under deps.dev:version directly). Also notes partial failure handling.

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 behavioral context by naming the specific catalog (apis.datos.gob.ar) and the returned fields (ids, titles, units, etc.), enhancing transparency without contradiction.

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

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

Two concise sentences, front-loaded with the primary action and resource. No unnecessary words or repetition.

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

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

For a search tool with 5 parameters and no output schema, the description covers the purpose, result fields, and language hint. It could mention pagination briefly, but the schema covers offset/limit. Overall, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds examples (e.g., 'inflacion') and reinforces the Spanish context, but does not provide significant additional 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 searches Argentina's national time-series catalog for series matching a keyword, with specific Spanish examples. It differentiates from sibling tools like get_series by indicating the returned ids are for use with it.

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

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

The description specifies using Spanish keywords and that results include ids for get_series, providing clear usage context. It does not explicitly state when not to use it or list alternatives, but the sibling context implies 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds specific mechanics: using BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and returning character offsets for verification. 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?

A single well-structured paragraph that front-loads the core action and adds details progressively. Every sentence adds value; no fluff.

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

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

Despite no output schema, the description fully explains what is returned (passages with offsets and similarity scores). It covers mechanics, limitations (200K char cap), and use cases (pairs with grounded verification). Complete for this simple tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical context beyond schema: explains 'top-N passages' for limit, provides example queries for query, and mentions truncation for text. This adds moderate additional 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 performs semantic search inside a fetched record, using a natural-language query to return top passages with offsets and scores. It distinguishes from siblings by explicitly mentioning its pairing with ask_pipeworx_grounded and its use case for large documents.

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 advises using the tool when a record is too large for the prompt, saving context by returning only relevant passages. It pairs with ask_pipeworx_grounded for grounding, giving workflow context. Lacks explicit 'when not to use' but provides strong 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?

The description adds substantial behavioral context beyond annotations: account requirement, type-specific parameters, delivery channel constraints (email validation, SMS cap, webhook signing secret, auto-disable). However, there is a potential contradiction: annotations include 'idempotentHint': true, but the description says 'Create... Returns the new subscription id', implying each call creates a new subscription (non-idempotent). This contradiction reduces trust. The description does not address idempotency 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 informative but lengthy; it efficiently packs details into several sentences. The purpose is front-loaded, followed by account requirements, type list, and delivery channels. Every sentence adds value, but the density could be improved with bullet points or clearer separation of concepts for easier scanning.

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 (3 parameters, nested objects, no output schema), the description covers most aspects: account requirement, type-specific use, delivery options, and constraints. However, it lacks explanation of idempotency behavior (important given annotation) and does not describe error scenarios or rate limits beyond SMS. Overall, it is complete enough for an agent to use the tool correctly.

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

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

With 100% schema description coverage, the description still adds significant meaning. For the 'type' parameter, it explains each enum value's use case and examples. For 'params', it provides detailed type-specific filters and required fields. For 'delivery', it clarifies channel behavior, constraints, and webhook security. This goes well beyond the schema's short 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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (create), resource (subscription to event stream), and output (subscription id). The tool name 'subscribe' aligns with this, and it is well-differentiated from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides clear when-to-use guidance with the phrase 'Create a proactive monitoring subscription' and explicit prerequisites: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It does not include explicit when-not-to-use or alternatives, but the sibling tools (e.g., 'unsubscribe', 'list_subscriptions', 'recent_alerts') provide implied context. The description could be improved by explicitly stating when to use 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/true/true/false. The description adds valuable context beyond that: it explains the tool is an onboarding entry point, returns 'category-bucketed example questions' drawn from a live catalog, and teaches how to call meta-tools. 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 front-loaded with the core purpose but includes a long list of synonyms ('What can I ask Pipeworx? / what is Pipeworx good for? ...'). While informative, it could be more concise. Still, all sentences earn their place.

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

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

Given no output schema, the description adequately explains what is returned (category-bucketed examples with tool calls). It covers when to use (first time, learning meta-tools) and parameter options. Complete enough for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with one optional parameter. The description adds examples ('finance', 'pharma', 'betting') and clarifies behavior when omitted (full spread). This adds meaning beyond the schema's brief 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 returns category-bucketed example questions with exact tool calls. It specifies the verb 'returns' and resource 'example questions', and distinguishes from sibling tools like ask_pipeworx by positioning itself as the onboarding entry point for knowing what to ask.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains calling with no arguments for full spread or passing a topic to focus. While it does not list when not to use, the context is clear and actionable.

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 value beyond annotations by detailing ownership enforcement, deactivation (not deletion), and the impact on historical events via recent_alerts. Annotations already indicate idempotent and non-destructive behavior, and the description aligns and adds 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 two sentences, concise and well-structured. The main action is front-loaded, and every sentence adds necessary context without 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 simplicity of the tool (one parameter, no output schema), the description covers the key behavioral aspects and side effects. It lacks explicit mention of return value or confirmation, but overall it is sufficiently complete for an agent to understand 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 a clear description for the single 'id' parameter. The tool description does not add additional information about the parameter beyond what the schema provides, so the baseline score is appropriate.

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

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

The description clearly states the action (cancel/unsubscribe), the target resource (subscription by id), and provides specific details about ownership enforcement and deactivation behavior. It effectively distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description specifies when to use the tool (to cancel your own subscription) and includes ownership constraints. However, it does not explicitly mention when not to use it or provide alternative tools for similar actions, 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 cover readOnly, openWorld, idempotent, and destructive hints. The description adds context about the return format (verdict, actual value, citation, delta) and the domain limitation, providing additional behavioral insight.

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, starting with trigger phrases, then use case, then details on domain and return values. It is slightly verbose but earns its length by providing essential context.

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

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

Given the single parameter and no output schema, the description adequately explains the return values and domain limitations. It provides enough context for an agent to understand the tool's capability and scope.

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 'claim' with schema coverage 100%. The schema description is clear, and the tool description adds minimal extra detail beyond the schema, making the baseline 3 appropriate.

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

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

The description clearly states the tool validates factual claims against authoritative sources, specifically company-financial claims via SEC EDGAR. It provides example trigger phrases and distinguishes itself by replacing 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and gives example queries. It does not explicitly mention when not to use it or list alternatives, but the guidance is clear enough.

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