Datos Co

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by detailing model choices (default Workers AI, optional Anthropic with BYO key), cost implications, and the return structure (per-model fields + combined view).

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 (3-4 sentences), front-loaded with the core action, and every sentence adds value without redundancy. No unnecessary detail.

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

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

Without an output schema, the description fully explains return values (per-model score, confidence, signals, raw_response + combined view). It also covers default model, API key usage, and primary use cases, 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?

With 100% schema description coverage, baseline is 3. The description enhances understanding by explaining the 'models' parameter's supported values and default behavior, the '_apiKey' requirement for Anthropic, and providing an example for 'context'.

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

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

The description clearly states the tool probes LLMs for entity knowledge and scores visibility per model (0-100), specifying output format and use cases. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring with per-model breakdown.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and implies appropriate contexts. While it doesn't explicitly state when not to use, the use case list provides sufficient 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 read-only, idempotent, open-world behavior. The description adds valuable context: the tool routes questions to one of 3804 tools across 907 sources, fills arguments, and returns structured answers with citation URIs. This enriches what annotations provide 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 two sentences long and front-loaded with the key advice. It is efficient and well-structured, though it could be slightly more concise by trimming the list of domains while retaining the important ones.

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 (many sources and tools) and the lack of output schema, the description adequately explains the routing mechanism, source breadth, and output format (citations). It could be improved by mentioning error handling or limitations for out-of-scope questions, but it is mostly 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%, and the description essentially repeats what the schema says about the parameters (all aliases for 'question'). It adds no new semantic meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: answering factual questions about current or historical data from a vast set of verified sources, explicitly preferring it over web search. It lists many domains and provides examples, making the purpose highly specific and distinguishing it from generic search 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 advises when to use the tool ('PREFER OVER WEB SEARCH') and lists many query types and example questions. However, it does not explicitly exclude when not to use or differentiate from siblings like 'deep_research' or 'ask_pipeworx_grounded', 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant detail: it costs one extra LLM call, returns structured refusal reasons (not_in_source, no_tool_match, etc.), and extracts answer only from tool result. 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?

Five sentences clearly structured: first states purpose, then explains process, return format, usage guidelines. No unnecessary words, front-loaded with key information.

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

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

Despite no output schema, the description fully details the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all failure modes. This is complete for a query tool with simple parameter 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 descriptions for each parameter. The description states 'Your question in natural language' and lists aliases, which adds minimal extra meaning beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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 'hallucination-resistant answer mode for high-stakes reads,' explains the process (picks tool, fetches data, extracts answer only from result), and distinguishes it from sibling 'ask_pipeworx' by noting the extra LLM call cost and use case.

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 to use for high-stakes reads where facts must not be invented (financial verdicts, legal claims, etc.) and recommends preferring 'ask_pipeworx' for casual lookups. This provides clear when-to-use and 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?

Annotations indicate read-only, idempotent, open-world behavior. The description adds rich behavioral context: fan-out to specific data sources per classifier, handling of low-confidence resolutions (status: 'low_confidence_match'), closed/dead markets (status: 'market_closed_or_inactive'), wide spreads (tradeability:'illiquid_wide_spread'), resolution-rule risk via cancellation_rule field, and news fields with fallback behavior. It also explains how the tool blocks on these conditions.

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 verbose, spanning multiple paragraphs with many examples (e.g., classifiers list, fan-out examples). While front-loaded with the main action, subsequent sections could be streamlined. The detail is valuable but reduces conciseness.

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

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

Given the tool's complexity (fan-out, resolution, analysis, cancellation rules) and absence of an output schema, the description thoroughly covers all key aspects: market matching confidence, evidence organization, parent event extraction, news fallback, safety mechanisms, and cancellation/void risk. It leaves little ambiguity for an agent.

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

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

Schema coverage is 100%. The description adds value beyond schema: for 'market', it explains acceptable formats (slug, URL, question text). For 'depth', it defines 'quick' vs 'thorough' and default. For 'include_raw', it describes when to use true (recompute deltas, cite observations) and false (summarized, ~20KB responses). This provides practical guidance for parameter selection.

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

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

The description explicitly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet), and method (pulling Pipeworx data). It distinguishes from siblings by focusing on comprehensive research including fan-out and comparison, which is not directly covered by sibling tools like 'polymarket_arbitrage' or 'polymarket_edges'.

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 scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives examples of classifiers and fan-out. However, it does not explicitly exclude cases where other tools might be more appropriate, nor does it mention alternatives among siblings.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behavioral details: it pulls latest 10-K data from SEC EDGAR/XBRL with proper fiscal year handling for companies, and FAERS counts for drugs. It also mentions sorting by primary metric and returning pipeworx:// citation URIs.

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 essential purpose and preference rule. Every sentence adds value, but it is somewhat lengthy. Some redundancy exists (e.g., repeating '2-5' multiple times), but overall it is well-structured 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?

Given no output schema, the description thoroughly covers return format (paired data with citation URIs), data sources for each type, and sorting behavior. It provides all necessary context for an agent to correctly use the tool.

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

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

Schema coverage is 100%, and the description adds significant meaning: it explains what each enum value ('company' vs 'drug') retrieves, gives examples for the 'values' parameter, and clarifies bounds (2-5 items).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It provides example phrases like 'Compare X and Y' and specifies the data sources for each type, distinguishing it from single-entity lookup tools like entity_profile.

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

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

The description explicitly advises preferring this tool over sequential single-pack lookups when comparing entities, with an 'ALWAYS PREFER' directive. It also gives concrete example phrases. However, it does not explicitly mention alternatives for single entity lookup, though entity_profile is a sibling.

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, so the description does not need to reiterate safety. It adds context about the return values (field name, label, type) and the prerequisite relationship, which is useful but not essential beyond annotations.

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

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

Two sentences with no wasted words. The first sentence immediately states the purpose and output, and the second provides usage guidance. Highly efficient.

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

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

For a simple tool with one parameter and no output schema, the description fully covers what the tool returns, how to call it, and where to get the input. No gaps remain.

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

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

Schema coverage is 100%, so the parameter is well-documented. The description adds value by explaining that datasetId is the 'Socrata 4x4 code from search_datasets', which provides context beyond the schema description 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 it lists columns (field name, label, data type) of a dataset from datos.gov.co. It distinguishes itself from sibling tools like query_dataset (which queries data) and search_datasets (which searches datasets) by specifying its role as a pre-query step.

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

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

Explicitly states 'Call this before query_dataset so you know which fields exist' and explains how datasetId is obtained from search_datasets. It provides clear usage context but does not explicitly mention when not to use it or list alternatives beyond the implicit workflow.

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=false. Description adds behavioral details: returns verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, explicit gaps[], never invents, and expects 15-60s response. 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?

Four sentences, front-loaded with core purpose, then details on methodology, usage, and requirements. 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?

Given complexity (parallel multi-source research, 3,804 tools, 907 sources) and no output schema, the description is complete: explains process, output structure (fields in packet), caveats (gaps, no invention), prerequisites, and timing. For a tool of this complexity, it is thorough.

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

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

Schema coverage is 100%, but description adds meaning: explains broad questions are fine, depth parameter maps to facet counts (quick=3, standard=5, thorough=8), and thorough needs a paid plan. This goes beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research in ONE call' by decomposing questions and parallelizing across 3,804 tools. It distinguishes from sibling ask_pipeworx for single lookups, providing a specific verb+resource+scope.

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

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

Description explicitly says 'Use for broad or multi-part questions' and contrasts with ask_pipeworx for single lookups. It also mentions prerequisites (Pipeworx account, paid plan for 'thorough' depth), offering clear when-to-use and 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: returns top-N tools with full schemas ready to call, and includes curated examples. 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 concise yet informative, front-loaded with the core purpose. The list of domains is useful but could be trimmed slightly without loss.

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

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

No output schema exists, but the description adequately explains what is returned (names, descriptions, schemas). Given the tool's simplicity and good annotations, it is complete enough for selection and 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 parameters are fully documented there. Description adds clarity by listing accepted aliases for query and giving examples, but does not significantly extend understanding beyond the schema.

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

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

The description clearly states it finds tools by describing the data or task, listing many specific domains (SEC filings, financials, FDA drugs, etc.). It distinguishes from sibling tools as the sole discovery/search tool among many specific-purpose 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 says 'Call this FIRST when you have many tools available and want to see the option set.' Provides clear when-to-use context, though does not explicitly state when not to use it.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds behavioral details: parallel fan-out across multiple sources, specific return fields (e.g., up to 5 filings with URIs), soft-fail for patents API, and news fallback. 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, starting with user queries for engagement, then stating the core purpose, usage guidelines, and detailed return fields. Every sentence adds value without redundancy.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete: it lists all sources, returned fields (with limits like 'up to 5 filings'), caveats (patents API sunset), and fallback mechanisms. 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 description coverage is 100%, so the schema already documents both parameters well. The description reinforces examples (e.g., 'AAPL', '0000320193') but does not add new meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: returning a full cross-source profile of a US public company. It uses concrete examples like 'Tell me about X' and specifies the verb 'profile', distinguishing it from siblings like compare_entities and resolve_entity.

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

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

The description explicitly advises preferring this tool over chaining single-pack lookups for holistic views. It also warns that names are not supported and directs users to resolve_entity first, providing clear when-to-use and 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?

Annotations already flag destructiveHint=true and idempotentHint=true. Description only restates deletion but adds no new behavioral details beyond annotations.

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

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

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

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

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

For a simple one-param tool with good annotations, the description covers purpose and usage. Could mention return behavior but not essential 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% with clear parameter description. The tool description adds no extra meaning beyond the schema.

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

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

Clear verb 'Delete', resource 'memory', and mechanism 'by key'. Distinguished from siblings 'remember' and 'recall' as the deletion counterpart.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Mentions pairing with remember and recall, indicating 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, idempotentHint, destructiveHint. The description adds behavioral details: fetches the page, extracts title/description/key links, and outputs a text blob ready for deployment. No contradictions.

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

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

The description is concise: three substantive sentences plus a bulleted 'Useful for' list. It is front-loaded with the main action and efficiently conveys key information without excess.

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

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

Given the tool's simplicity (2 params, rich annotations, no output schema), the description covers purpose, process, output format, and use cases. Missing edge cases or output format specifics are minor given annotation coverage.

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

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

Input schema provides full coverage with descriptions. The description reinforces the role of 'url' and 'max_links' by explaining the extraction process, adding context 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 it generates a production-ready llms.txt file for any URL, specifying the output format and its utility for AI crawlers. It distinguishes itself from sibling tools like ai_visibility_check by focusing on file generation rather than presence checking.

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 explicit use cases (client's site, own project, competitor audit) which guide when to use the tool. It does not explicitly mention when not to use or name alternatives, but the context is clear enough.

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, destructiveHint=false, idempotentHint=true. Description adds context by specifying return fields and the optional parameter behavior, but the core traits are covered by annotations.

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

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

Three sentences: purpose, return fields, usage guidance. No fluff, front-loaded with 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?

Tool is simple with one optional parameter. Description covers purpose, usage, return fields, and parameter behavior. No output schema, but the description enumerates return fields. 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_description_coverage is 100% for the single parameter (include_inactive). The description does not add new information beyond the schema; it only reinforces the default value. Baseline 3 as per guidelines.

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 'List the caller's active subscriptions' with a specific verb and resource. It lists return fields and distinguishes from sibling tools like subscribe and unsubscribe by focusing on reading existing 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 the AI when to use this tool versus alternatives (subscribe, unsubscribe).

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

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

Annotations (readOnlyHint=false, destructiveHint=false, etc.) are minimal, but the description adds key behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against quota, team reads digests daily, signal affects roadmap. 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?

Four sentences, each serving a distinct purpose: (1) declares purpose, (2) gives usage scenarios, (3) provides formatting guidance, (4) states rate limits and cost. No redundancy; information is front-loaded and easy to scan.

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 with 3 parameters, no output schema, and one nested object, the description covers all necessary context: when to use, what to include, constraints (rate limit, cost), and impact. The agent has everything needed 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 descriptions for each parameter, but the main description adds valuable nuance beyond schema: explains the enum values in context, advises specificity, and sets message length expectation. The description enhances understanding of how to use each parameter effectively.

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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and distinctly separates from 28 sibling tools by being the dedicated feedback channel.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also instructs what to avoid: 'don't paste the end-user's prompt.' This clearly tells the agent when and how to invoke 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds that data is self-aggregating from CF analytics engine, no PII, and cached 5min-1h, offering useful behavioral context beyond annotations.

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

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

Four sentences, clearly front-loaded with return values, use cases as bullet-like list, no redundant wording. Every sentence adds value.

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

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

With no output schema, description adequately explains returns (top tools, top packs, total call volume). Caching detail and window explanations fill gaps. Could mention count or format but still complete enough.

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% parameter details, and description enriches by explaining that shorter windows surface 'what's hot right now' while longer windows show 'steady-state demand', plus documents default window.

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 'Returns the top tools, top packs, and total call volume' over a recent window, distinguishing itself from siblings like 'discover_tools' by focusing on trending/call volume data.

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

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

Lists three specific use cases (discovering hot data, confirming canonical tool, aligning use case) and explains window selection semantics. Lacks explicit when-not-to-use, but provides strong contextual 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 goes far beyond annotations, detailing internal checks like Jaccard similarity, partition filters, and fill checks. It explains behavioral traits such as requirement for event or topic, rejection of placeholder partitions, and realizable edge calculation. No contradictions with annotations.

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

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

The description is detailed and front-loaded with the requirement clause and purpose. While every sentence adds value, it could be slightly more concise. However, given the complexity, it is well-structured.

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

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

Despite lacking an output schema, the description explains the response structure (opportunities[], partition_check, fill_check) and references sibling tools. It covers all necessary behavioral aspects for an AI 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?

Schema coverage is 100%, but the description adds significant context: event slug examples, topic seed question examples, and behavioral differences between modes. This adds value 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (event and topic) and provides concrete examples, making it 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 explains when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also notes that calling with no args fails and mentions when to use the sibling tool polymarket_fill_risk for custom sizing.

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 (readOnly, idempotent, etc.), the description richly details internal model families, response segments, diagnostics for empty results, caching behavior, and limitations like Fed data unreliability. No contradiction with annotations.

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

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

The description is very long and detailed, with some redundancy (e.g., listing all three segments then repeating). It is well-structured with clear sections, but could be more concise without losing critical information.

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

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

Despite lacking an output schema, the description fully explains the response structure, diagnostics, and edge fields. It addresses why Fed bets are excluded and how caching works. Covers all necessary context for a complex tool with 9 parameters.

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 for tradeable-edge knobs (min_liquidity, max_spread_pp) and explains how min_partition_leg_kelly applies differently. This enhances understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for discovery without paging. It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx-driven edge detection.

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

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

The description provides context for use ('what should I bet on today') and explains parameter knobs for tradeability, but does not explicitly compare with sibling tools or state when not to use this tool. Implicit guidelines are present but not exhaustive.

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. The description adds critical behavioral details: history bounded by 60-day TTL, gaps due to cache-miss, decay from daily closes not intraday, and comprehensive response field explanations. 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?

Well-structured with clear sections (purpose, args, response fields, limits). Front-loaded with the core question. Slightly long but all information is valuable and 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?

No output schema, but description thoroughly explains response structure: tracked[], expired[], snapshot_dates[], including field semantics (trend values, decay derivation, edge_pp_net sign). Also covers limits. Very 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%, and description reiterates parameters with extra context (e.g., 'snapshot family' for window, default 14 for days). Adds meaning beyond schema by explaining that window selects the polymarket_edges snapshot family.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, explicitly distinguishing it from raw edge data (sibling polymarket_edges) by answering 'how long has this edge existed and is it shrinking?'. It uses specific verbs and resources.

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

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

Provides context on when to use (e.g., fresh vs old wide edges are different trades) and explains response structure and limits (60-day TTL, snapshot gaps). Does not explicitly list when not to use or name alternatives, but sibling context makes it 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, read-only operation. The description adds behavioral details: it walks the order-book ladder, checks depth, returns a verdict (clean/degraded/cannot_fill), and warns about thin books and unhedged directional risk. This fully aligns with and expands upon the 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 lengthy but dense with valuable information. It front-loads the core purpose, then breaks down modes and return values, and ends with a strong usage guideline. Every sentence contributes meaning, though some redundancy exists (e.g., repeating verdict values already implied). Still, for the complexity, it is well-structured.

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

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

Given no output schema, the description fully explains all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also covers edge cases like partial fills and directional risk, making it complete for agent decision-making.

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 each parameter having a clear explanation. The description further enriches understanding: it details the REQUIRES one-of constraint for market/event, explains default side behavior for basket mode (auto based on partition sum), and clarifies size_usd interpretation for single-market vs basket (settlement notional vs spend/target). This adds significant value beyond the schema.

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

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

The description clearly defines the tool as a realizable-vs-theoretical edge check against live order-book depth, with distinct single-market and basket modes. It specifies what each mode returns (top_of_book, vwap_fill_price, verdict, etc.) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by serving as a prerequisite risk check.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It provides clear rationale for why this is necessary (theoretical overround may not be capturable, partial fills create directional risk) and specifies that exactly one of `market` or `event` is required.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description details compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and the fact that spreads are rare. This provides full transparency 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 well-structured, starting with the core purpose, then modes, response, and safety fields. It is detailed but some sentences are lengthy; however, 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 the complexity of cross-venue comparison and no output schema, the description thoroughly explains the response format, safety fields, and limitations. It is complete for an AI 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%; the description adds meaning by listing the allowed topic values and explaining how parameters interact (e.g., explicit overrides topic). It provides context beyond raw schema properties.

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 spread between Kalshi and Polymarket for the same resolving question, explaining two modes (topic shortcuts and explicit tickers). It distinguishes itself from sibling tools like `polymarket_arbitrage` by focusing on cross-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 provides explicit guidance on when to use each mode, warns that most pre-mapped topics yield compatibility warnings, and explains the safety fields to detect non-equivalent bets. It effectively tells the agent when the output is meaningful and when it is not.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable context: it specifies the return format (array of row objects), default $limit of 50, Socrata max per page of 50000, and includes examples of SoQL clause syntax. 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 compact yet highly informative. It starts with the core purpose, then explains the key parameter (datasetId), lists SoQL clauses with examples, provides usage advice, and ends with return format and limit information. Every sentence adds value; no redundancy.

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

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

Given the complexity of the tool (8 parameters, SoQL query language), the description covers major aspects: purpose, parameter roles, usage flow, return format, and default limit. It could explicitly mention pagination via $offset, but this is implied by the $limit description. No output schema exists, but return format is described. Overall, it provides nearly complete context 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?

Although schema description coverage is 100%, the description adds significant value beyond the schema by explaining each SoQL clause with concrete examples (e.g., $select: 'departamento_nom, count(*)', $where: 'departamento_nom=\'BOGOTA\' AND edad > 60'). It also clarifies default limit and offset behavior, and explains the relationship between parameters.

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 queries rows from a datos.gov.co dataset using SoQL. It clearly identifies the resource (dataset identified by Socrata 4x4 code) and the action (query with SoQL clauses). The tool is distinguished from sibling tools like dataset_columns and search_datasets, which serve different purposes.

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 guidance on prerequisites: use search_datasets to obtain the datasetId and use dataset_columns to learn field names before querying. It explains when to use this tool in the context of a workflow. It does not explicitly state when not to use or list alternatives, but the guidance is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining scope per identifier and pairing with other 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?

Three sentences, efficient and front-loaded with purpose. 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 tool with one optional parameter and no output schema, the description covers behavior, scope, and pairing completely.

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 main description reinforces its usage (omit to list). Adds meaning beyond schema.

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

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

Description clearly states the tool retrieves a value saved via remember, or lists all keys if omitted. It explains the purpose: to look up context stored earlier. 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?

Description explains when to use (retrieve stored context) and how (omit key to list all). It doesn't explicitly state when not to use, but the context is clear and pairs with remember/forget.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: mark_read modifies read state (idempotent but stateful), event payload details, and polling safe. No contradictions with annotations.

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

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

The description is five sentences well-structured: main purpose, return fields, filtering, mark_read behavior, and alternative access. Each sentence adds necessary information without redundancy. Could be slightly tighter but 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 no output schema, the description adequately explains return fields (source, citation_uri, raw payload). It covers all key aspects: purpose, filtering, mark_read, polling suitability, and fallback HTTP endpoint. No gaps for a 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% with descriptions for all 5 parameters. The description adds value by providing concrete examples (e.g., 'sec_8k' for 'type'), explaining the effect of 'mark_read' beyond schema, and confirming 'since' expects ISO timestamps. This elevates beyond baseline 3.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed'. It distinguishes from siblings like 'list_subscriptions' (which lists subscriptions themselves) and 'recent_changes' (which tracks changes).

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 context for usage: filtering options, mark_read behavior, and suitability for polling. It mentions an alternative HTTP endpoint for scripts/dashboards, but does not explicitly exclude other sibling tools 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: fans out to multiple APIs, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure (grouped changes, citations). No contradictions.

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

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

The description is concise yet comprehensive, front-loaded with natural language queries. Every sentence adds necessary detail without repetition. Perfectly structured for an 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?

Despite lacking an output schema, the description clearly states return structure (changes[], total_changes, citations). It covers all key aspects: inputs, sources, fallbacks, and limitations. No missing critical information 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%, but description adds value beyond schema: clarifies 'since' accepts ISO or relative with recommended defaults, explains 'value' as ticker or CIK with example, and notes 'type' only supports 'company'. This helps correct usage.

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

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

The description explicitly states the tool provides a change feed for a company within a time window, listing data sources (SEC, GDELT/GNews, USPTO) and example queries like "What's new with X". It clearly distinguishes from sibling tool entity_profile, which serves 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 gives explicit when-to-use guidance: use for recent changes vs entity_profile for static profiles. It also provides input format details (ISO date or relative shorthand) and example tickers/CIKs.

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 write operation and idempotency. The description adds key-value scoping by identifier, persistence details (authenticated vs 24-hour anonymous), and lifecycle 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 a single paragraph but well-organized: purpose, usage guidance, behavior, and sibling references. Every sentence adds value 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 no output schema, the description adequately covers storage scope, lifetime, and paired tools. It provides enough context for the agent to understand the tool's role and behavior.

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

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

Parameter descriptions in the schema cover 100% with examples. The description does not add additional meaning beyond the schema, meeting the baseline expectation.

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

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

The description clearly states 'Save data the agent will need to reuse later' with specific examples like 'resolved ticker, target address, user preference'. It distinguishes the tool from siblings 'recall' and 'forget' by mentioning them explicitly.

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 says 'Use when you discover something worth carrying forward' providing clear context. It also directs pairing with recall and forget. While it doesn't mention situations where not to use, the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral context by noting that each call cascades through multiple lookup endpoints internally, replacing 2-3 manual calls. However, it does not discuss error handling or edge cases like ambiguous names.

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 with some internal structure (use cases, supported types). It is efficiently written without wasted words, though a bullet list could improve readability. Overall, it is concise and front-loaded with key information.

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

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

Given the tool's moderate complexity, the description covers all necessary aspects: purpose, when to use, input examples, supported types, return value details, and internal behavior. Without an output schema, the description adequately explains what the agent can expect. 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 description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by specifying the input formats (e.g., ticker, CIK, name for company; brand/generic for drug) and detailing the return values (ticker+CIK+company_name for company, RxCUI+ingredient+brand for drug). This compensates for the lack of output 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 uses specific verbs ('resolve', 'look up') and clearly states the action: mapping a user-spoken name to an official identifier. It provides concrete examples of queries and distinguishes the tool's role as the first step when an ID is needed. While sibling differentiation is not explicit, the purpose is unmistakable.

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

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

The description explicitly states when to use the tool ('Use FIRST whenever you have a name but need an ID') and gives example use cases. It does not explicitly list when not to use or name alternatives, but the context is clear enough for an AI agent to infer 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, openWorldHint, idempotentHint, destructiveHint. The description adds that it calls ai_visibility_check internally and returns a ranked list with score, confidence, signal density, which is beyond annotation 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 two sentences with a usage example, front-loaded with the core action. Every sentence adds value; no redundancy or unnecessary detail.

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 (comparison, no output schema, good annotations), the description covers purpose, usage, and output format sufficiently. It lacks explicit error handling or limitations, but 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?

Input schema has 100% description coverage for all 4 parameters. The description does not add parameter-specific details beyond what schema provides, so baseline score of 3 is appropriate.

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

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

The description uses specific verbs like 'compare', 'probes', 'ranks', 'surfaces' and clearly distinguishes the resource ('AI visibility across multiple entities'). It differentiates from sibling 'ai_visibility_check' which likely handles single entities.

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

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

Explicitly states 'Useful for competitive AI-marketing audits' and gives a concrete example question. Context signals imply when to use (side-by-side comparison) but does not explicitly list when not to use or alternatives beyond the implied ai_visibility_check.

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 behavioral details beyond annotations: fans out across deps.dev and bundlephobia, returns specific fields, handles partial failures gracefully with 5-30s timeout, and lists 'sources_failed'. Annotations declare readOnly, openWorld, idempotent; description confirms and adds nuance.

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 purpose, then details. Every sentence adds value, though slightly lengthy. Could be trimmed slightly without losing meaning.

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

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

No output schema, but description fully covers return values: summary block fields, per-advisory detail, links, alternative versions. Also explains error handling. Highly complete for a complex tool.

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

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

Adds context beyond schema: scoped packages accepted, default version is latest. Schema has 100% coverage, but description reinforces and clarifies usage for both parameters.

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 'scan' with 'dependency' specifying npm package addition check. Distinguishes from siblings by explicitly stating 'NPM ecosystem only in v1' and directing other ecosystems to 'deps.dev:version directly'.

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: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also tells when not to use: non-NPM ecosystems, pointing to alternative.

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. The description adds value by specifying the portal, return format, and bilingual query capability, which are not in annotations.

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

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

Two sentences with no redundancy. The main action and key details are front-loaded, and every sentence contributes 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?

For a search tool with 3 simple parameters and no output schema, the description fully covers purpose, return content, and integration with sibling tools. No gaps given the annotations already handle safety and idempotency.

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 three parameters. The description adds extra meaning: it notes that query terms can be Spanish or English, providing useful context beyond the schema.

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

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

The description uses a specific verb ('search'), identifies the exact resource ('Colombia's open-data portal datos.gov.co'), lists return fields, and distinguishes from siblings by mentioning the id usage with dataset_columns and query_dataset.

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 clearly states the tool searches datasets and explains how to use the returned id with related tools. It implies when to use this tool (searching) versus siblings (column analysis or data retrieval), but does not explicitly exclude alternative contexts.

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

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

Details embedding model, window size, character cap, and truncation behavior, adding substantial value beyond annotations that only indicate read-only and idempotent.

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

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

Dense single paragraph with purpose, usage, and internals; no wasted words, but could be slightly more structured with bullets.

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

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

Given no output schema, the description fully explains return format (passages, offsets, scores) and limitations (truncation, cap), making it 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 examples for query and notes the 200K char limit for text, enhancing understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, distinguishing it from siblings like search_datasets and ask_pipeworx by emphasizing it works on text already retrieved.

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 ('when the record is too big to cram into the prompt') and pairs with ask_pipeworx_grounded, providing a clear alternative workflow.

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 idempotentHint=true and destructiveHint=false. The description adds significant behavioral context: requires OAuth, subscription persistence, delivery channel specifics (always-on feed, optional email/sms/webhook with limits), and webhook HMAC signing. No contradictions, and it goes well beyond annotations.

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

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

The description is a single paragraph that front-loads the core purpose and requirements, then provides detailed type and delivery info. It is somewhat dense but every sentence adds value. Could benefit from bullet points for readability, but remains effective and 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?

Given no output schema, the description appropriately mentions the return value (subscription id) and explains delivery channels and constraints. It covers setup requirements (OAuth, phone verification) and error conditions implicitly (SMS cap, webhook auto-disable). Could be slightly more explicit about the response structure, but is generally complete 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% with descriptions for all parameters. The description enriches this by providing real examples for each type (e.g., sec_8k items codes, polymarket_edge topic), clarifying optionality (items? optional), and detailing delivery object fields with verification requirements and caps. This adds practical 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's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb ('Create') and resource ('subscription'), and it distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies required account type (Pipeworx OAuth), lists supported subscription types with example parameters, and details delivery channels and their constraints (SMS cap, webhook auto-disable). It implicitly tells when to use (when creating a subscription) but does not explicitly mention when not to use or suggest alternatives, though siblings are distinct.

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 context about the output structure (category-bucketed examples with tool+argument shape) and that results come from a live catalog, enhancing 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 moderately long but well-structured with examples, usage patterns, and a clear statement of purpose. It could be slightly more concise, but every sentence adds value.

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

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

Given no output schema, the description adequately covers the output format and usage scenarios. The tool is simple with low complexity, and the description provides all needed 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% for the single optional 'topic' parameter. The description adds value by explaining that omitting the parameter gives a cross-category spread and provides example values, going 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 returns example questions about Pipeworx's capabilities, categorized by topic. It uses specific verbs ('return') and resources ('example questions') and distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by framing it as an onboarding entry point.

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

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

The description explicitly advises using this tool first when unfamiliar with Pipeworx, and provides guidance on optional topic parameter usage. While it doesn't explicitly list when not to use it, the context makes it 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 indicate non-readonly and non-destructive; description adds ownership enforcement and deactivation behavior, providing value beyond annotations.

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

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

Two sentences, concise and front-loaded with action and key constraints; 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 one-parameter tool with annotations, description adequately explains ownership and deactivation; could mention return value but not required as output schema absent.

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 mentions 'by id' but adds no new semantics beyond what the schema provides (subscription id from subscribe).

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

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

The description uses a specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing from siblings 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 implies usage for canceling owned subscriptions but does not explicitly state when to use this over alternatives or when not to use it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds that it returns a verdict, extracted structure, actual value with citation, and percent delta, and mentions the data source (SEC EDGAR+XBRL). No contradictions with annotations.

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

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

The description is moderately long but well-structured: starts with examples, then usage, then technical details. Every sentence adds value, though some minor redundancy could be trimmed. 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?

For a tool with one parameter, no output schema, and thorough annotations, the description fully covers functionality, usage domain, return values, and data source. It is complete and self-contained.

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

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

Schema coverage is 100% with a description for the single 'claim' parameter. The tool description adds multiple examples and clarifies the natural-language format, providing 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's purpose: verifying natural-language claims against authoritative sources, specifically company-financial claims. It provides example queries and differentiates from siblings by being the only claim verification tool.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain. It lacks explicit when-not-to-use but provides sufficient context for appropriate use.

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