Datos Cl

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: the default model is free, passing `_apiKey` probes Anthropic with the user paying directly, and it returns a structured per-model object plus combined view. No contradiction with annotations exists.

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

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

The description is three sentences, front-loaded with purpose, then key behavioral details, then use cases. Every sentence carries useful information with no redundancy or 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?

Without an output schema, the description appropriately discloses the return structure (per-model score, confidence, signals, raw_response) and combined view. It also covers default model and optional Anthropic call. Minor gaps exist (e.g., how scoring works, what 'signals' include), but overall it is sufficient for a read-only probe with strong annotations.

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 baseline is 3. The description enhances parameter understanding by explaining the default model behavior (workers-ai free), the purpose of `_apiKey` (BYO key, direct payment to Anthropic), and how `models` works when omitted. This adds meaning beyond the schema's field 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 a specific verb ('probe') and resource ('one or more LLMs') with a well-defined scope: scoring visibility (0-100) per model for a business/brand/product/topic. It also mentions the default model and return format, making it highly specific and distinct from siblings like scan_competitor_ai_presence, which is competitor-focused.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context for when to use the tool. However, it does not mention when not to use it or name alternative tools for different scenarios, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint false. Description adds context: routes to thousands of tools, returns stable pipeworx:// citation URIs, works on every tier, one fast call. No contradiction.

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

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

Long but front-loaded with 'PREFER OVER WEB SEARCH' and every section serves a purpose: domain list, trigger phrases, examples, alternatives. Dense but well-organized; only minor deduction for its wall-of-text format.

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

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

For a complex tool with no output schema, the description covers purpose, domains, examples, trigger phrases, return format (structured answer with citation URIs), and escalation paths to sibling tools. Fully complete for selection and invocation decisions.

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 documents six parameters, all aliases of question, with 100% coverage. Description does not add parameter-specific meaning beyond noting it accepts natural language questions. Baseline 3 applies since schema is already rich.

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 routes factual questions to 5,564 tools across 1,462 sources, fills arguments, and returns structured answers with citation URIs. It distinguishes from siblings by explicitly positioning it as the default entry point and contrasting with alternatives.

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 instructs to prefer over web search, provides trigger phrases ('what is', 'look up', 'find', 'get the latest', etc.), and specifies when to use alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. Also covers breaking news routing.

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?

Given the rich annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds significant context beyond them: it explains the beta nature, that candidate routing may be active at times, the current inactive state, and that it is a full working router with no fallback. It also confirms the same response shape, giving a complete behavioral picture 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 four sentences long but each sentence adds essential information: beta relationship, current state, usage instruction, and reassurance that it's fully functional. It is front-loaded with the key concept 'Beta version of ask_pipeworx'. Slightly more verbose than strictly necessary, but every sentence earns its place.

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

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

For a beta router tool, the description covers all necessary context: what it does, how it relates to the stable version, when to use it, current operational state, and response shape. With annotations covering safety and idempotency, and no output schema needed (same response shape as sibling), the description is complete for an agent to select and invoke it correctly.

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

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

The input schema has 100% coverage, with all properties described (question and its aliases). The description doesn't add parameter-specific details beyond stating 'same arguments' as ask_pipeworx, which is redundant given the schema. Baseline of 3 is appropriate since the schema already carries the semantic weight.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that handles the same 5,564 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements and the experimental edge, making it clear what the tool does and how it differs from siblings.

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

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

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It also clarifies the current state (no active candidate, so it matches ask_pipeworx exactly), implying when to choose this over the stable version. This effectively tells the agent when to use it and references the 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?

The description adds significant behavioral detail beyond annotations: it explains the refusal reason field, the evidence extraction from verbatim quotes, the extra LLM call cost, and the fact that it only uses the tool result. No contradiction with readOnlyHint, idempotentHint, or destructiveHint.

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

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

The description is long but dense with critical information about refusal reasons, usage context, and cost trade-offs. No filler words; every sentence adds value given the tool's complexity. Could be slightly tightened but 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?

For a tool with no output schema, the description fully specifies the return format ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and the refusal reasons. It also covers when to use and the cost overhead, making it complete for an agent to decide and invoke correctly.

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

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

The schema already describes the question parameter and all aliases with 100% coverage, so the description does not need to add much. It doesn't go beyond schema but the baseline of 3 is appropriate given the simplicity of the parameter.

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

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

Clearly describes the tool as a hallucination-resistant answer mode that extracts answers from tool results with evidence, and explicitly differentiates it from ask_pipeworx by its refusal behavior and evidence extraction. The verb 'answers' and resource 'grounded mode' are specific and distinguish it from siblings.

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

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

Explicitly states when to use ('high-stakes reads', 'whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), and names the alternative tool. Includes cost trade-off 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 read-only and idempotent behavior, but the description goes far beyond them. It discloses the resolver contract with confidence levels, suppression of analysis on low-confidence matches, blocking statuses for closed/inactive markets, illiquid wide-spread warnings, GDELT fallback fields, and cancellation-rule risk. This is exceptional behavioral transparency.

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

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

The description is long but well-structured with uppercase section labels (FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making it scannable. Most sentences carry valuable technical content, but the length is near the upper limit and a few details could be tightened without losing 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?

Despite having no output schema, the description thoroughly covers return shapes, resolver match fields, parent-event extraction, news fallback behavior, safety short-circuits, and resolution-rule risk. It leaves very little ambiguous about how the tool behaves in diverse scenarios.

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

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

Schema coverage is 100% and the schema already explains the 'market' parameter's accepted forms, 'depth', and 'include_raw'. The description largely restates the input format and adds fan-out examples, but does not introduce new parameter semantics beyond what the schema provides. This matches the baseline of 3 for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly identifies the tool's function and scope, and even gives example use cases. However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_arbitrage, so it lacks sibling differentiation.

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

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

The description clearly states when to use it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides concrete examples and categories. It does not mention exclusions or explicitly point to alternatives among sibling tools, which keeps it from a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds rich context: data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled, handling of off-calendar fiscal years, sorting behavior, and citation URIs. This goes well beyond annotation coverage.

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

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

The description is somewhat long due to enumerated trigger phrases, but every sentence contributes functional or behavioral information. It front-loads usage patterns and keeps the structure logical, making the length acceptable.

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

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

Given the tool's simplicity (2 params, no output schema) and the presence of annotations, the description adequately covers expected data, sorting, and return format. It does not mention error cases or limitations, but that is not a critical gap for a comparison 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 descriptions cover both parameters, but the description reinforces semantics with concrete examples (AAPL, MSFT, ozempic) and explains what each type returns. This adds value over the schema by linking parameter values to their data implications.

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

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

The description clearly identifies the tool as performing side-by-side comparisons of 2-5 companies or drugs, with explicit trigger phrases and a specific resource. It distinguishes itself from sequential lookups by asserting 'ALWAYS PREFER over sequential single-pack lookups,' making its scope 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?

It states when to use the tool ('when comparing entities') and explicitly instructs preferring it over sequential single-pack lookups. However, it does not name specific alternative tools (e.g., entity_profile) or state when not to use it, such as for single-entity queries.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing account/paywall requirements, parallel decomposition, findings packet structure, gaps[], contradictions[], citation_uri fetchability guarantees, semantic excerpting, and latency expectations. It also clarifies what happens when the topic is not in the structured catalog.

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

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

The description is long but dense and front-loaded with the most critical fact (account requirement). Almost every sentence adds distinct operational or usage value; however, some points like the contradictions[] scan are mentioned both in the depth explanation and in the body, creating minor redundancy.

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

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

For a complex orchestration tool with no output schema, the description is remarkably complete: it describes the findings packet fields, gaps and contradictions behavior, citation resolution guarantees, latency, account tiers, and clear sibling alternatives. No critical behavioral area is left unexplained.

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 already 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the paid-plan requirement for depth:'thorough', the second-hop behavior of standard vs thorough, and that broad/multi-part questions are appropriate for the question parameter.

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

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

The description clearly states the tool performs multi-source structured research across Pipeworx's 1462 data sources, decomposing questions and routing facets to tools in parallel. It also distinguishes itself from siblings by explicitly saying it is NOT open-web search and by naming ask_pipeworx as the alternative for other use cases.

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

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

Usage guidance is explicit: use deep_research for broad/multi-part structured-data questions, use ask_pipeworx for single lookups or breaking/current-news topics, and fall back to ask_pipeworx when not signed in. The description names alternatives and gives clear conditions, plus depth-tier guidance for standard vs thorough.

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 safety is clear. The description adds valuable behavioral context: it returns top-N results with names, descriptions, and full schemas, each 'ready to call directly, no second schema lookup needed.' This goes beyond annotations and helps the agent understand the tool's output and efficiency.

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, front-loaded paragraph that states purpose first, then lists use cases and return behavior. The domain list is somewhat long but informative, and every sentence serves a purpose. It could be tightened but remains 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?

With no output schema, the description compensates by explaining the return format (top-N tools, names, descriptions, schemas, examples) and readiness for direct invocation. It also covers when to use it first. Though it doesn't discuss edge cases or limits beyond the schema, it is sufficient for a discovery tool with good annotations.

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

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

Schema description coverage is 100% and each parameter (including aliases) is well-documented in the schema itself. The description adds no new parameter semantics beyond the schema, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes this as a meta-tool for browsing/discovering other tools, and even enumerates the covered domains. This fully separates it from sibling tools that perform specific data tasks.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It lacks explicit when-not-to-use or named alternatives, so it doesn't earn a 5.

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: it fans out across multiple data sources, returns specific fields, notes the USPTO API sunset with soft-fail behavior, and describes the GDELT→GNews fallback for news. This gives a rich picture of what happens during execution.

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?

Although the description is long, every sentence provides value: usage examples, strategic preference, fan-out behavior, return details, and parameter guidance. It is front-loaded with relatable queries and structured logically, making it easy to scan despite its length.

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

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

Given the tool's complexity (cross-source aggregation, multiple fallbacks) and no output schema, the description thoroughly explains what is returned (cik+company_name, filings with URIs, fundamentals, patents, news, LEI) and the key limitation (names not supported). This is complete enough for an agent to invoke correctly.

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

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

Schema covers both parameters with 100% coverage, including examples. The description adds practical semantics by specifying 'Pass ticker "AAPL" or zero-padded CIK "0000320193"' and reiterating the name restriction, which reinforces the zero-padding requirement beyond the schema's text.

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 opens with concrete user phrasings and defines the tool as 'full cross-source profile of a US public company in ONE parallel call.' This clearly identifies the verb (profile) and resource (US public company) while distinguishing it from sibling tools like resolve_entity and single-source lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and notes that names are not supported, directing users to 'use resolve_entity first.' This provides clear when-to-use and alternative 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 include destructiveHint=true and idempotentHint=true, so the description's 'Delete' adds no new behavioral information. It adds the motivational context of clearing sensitive data, but does not disclose any additional behavioral traits beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the core action, and every word earns its place. It is concise and 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?

This is a simple tool with one parameter, annotations covering destructiveness, and no output schema needed. The description fully covers the operation, use cases, and relationship to sibling tools, making it complete 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?

The schema covers the single 'key' parameter with a clear description ('Memory key to delete'), and schema coverage is 100%. The description merely restates 'by key' without adding extra meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by describing exactly what it does.

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 this tool ('when context is stale, the task is done, or you want to clear sensitive data') and even points to sibling tools ('Pair with remember and recall'). This provides clear context and differentiation.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds meaningful behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and notes the output is a single text blob. This exceeds the baseline and provides useful process transparency beyond 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 two sentences plus a short use-case list. Each sentence earns its place: purpose, behavior/outcome, and scenarios. There is no fluff, and key information is front-loaded in the first sentence.

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 fetch-and-generate tool with no output schema, the description covers the output format ('single text blob'), the process, and the use cases. Annotations and schema handle safety and parameters, so the description is sufficiently complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for both parameters (url and max_links), and the description does not add additional semantic detail beyond what the schema already states. With full schema coverage, a 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 clearly states the specific verb ('Generate') and resource ('llms.txt file') for any URL, and explains the outcome (emitting standard llms.txt markdown). It also lists concrete use cases that distinguish it from sibling tools like scan_competitor_ai_presence or ai_visibility_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 provides clear contexts for use via the 'Useful for' list (client indexing, personal project drafting, competitor auditing), but it does not explicitly name alternative tools or state when not to use it. This is clear context yet lacks explicit exclusions, aligning with a score of 4.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the all_fields behavior and confirms this is a CKAN listing, but omits behavioral details such as pagination semantics or result ordering. With strong annotations, this is adequate but not richer than required.

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

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

Two concise sentences front-load the purpose and add one actionable tip. No fluff or redundant restatement of the title.

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

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

For a simple read-only list tool with comprehensive annotations and an output schema, the description covers the core purpose, source, and main flag. It lacks explicit pagination guidance for limit/offset, but those are optional and inferable, so the description is nearly complete.

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

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

Schema description coverage is 0% and the description only explains all_fields=true for names and descriptions. limit and offset semantics (e.g., pagination, zero-based offset) are left entirely to inference, so the description does not sufficiently compensate for the absent schema descriptions.

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

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

Clearly states the exact action ('list thematic groups/categories') and identifies the specific catalogue (datos.gob.cl CKAN) and scope (organise Chilean open datasets). The verb+resource structure distinguishes it from sibling group_show, which retrieves a single group.

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 clear context ('used to organise Chilean open datasets') and a conditional parameter tip, but does not explicitly state when to choose this over alternatives like group_show or organization_list. Usage context is implied rather than explicitly delineated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context: the optional inclusion of datasets via include_datasets and the specific catalogue name. 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 a single, front-loaded sentence with no wasted words. It efficiently communicates the data source, the action, the resource, and the optional behavior.

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

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

Given the simple tool (2 parameters, output schema present, safety annotations), the description is largely complete. It covers purpose, parameters, and data source. It could mention alternative tools, but that is a usage guideline concern, not a completeness gap.

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

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

Schema description coverage is 0%, but the description compensates by explaining that the group is identified by ID and that datasets can be optionally included. This gives both parameters (id, include_datasets) clear meaning beyond the raw 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 function: retrieving full detail for a thematic group by ID, including title, description, and optionally contained datasets. It identifies the specific data source (Chilean CKAN) and is distinct from sibling tools like group_list or package_show.

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

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

The description gives clear context: use this tool when you have a group ID and need its details. It does not explicitly mention alternatives or when not to use it, so it falls short of a 5, but it clearly implies the appropriate scenario.

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?

With readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations already covering safety and side effects, the description adds value by specifying the scope (caller's active subscriptions), the return fields, and the default behavior (active only). It does not disclose potential limitations like pagination, but annotations lower the bar.

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 pack purpose, return fields, and usage guidance without any wasted words. The structure front-loads the action and follows with relevant context, making it 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 list tool with one optional parameter, the description is complete: it lists return fields, specifies scope, and gives usage guidance. Since there is no output schema, the description adequately carries the return value information. No significant gaps.

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

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

Schema coverage is 100% with the parameter include_inactive clearly described ('Include cancelled subscriptions in the response (default false)'). The description's mention of 'active subscriptions' and 'cancel' slightly hints at the parameter but doesn't add meaningful detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions, enumerates the return fields (id, type, params, created_at, last_fired_at, fire_count), and distinguishes it from sibling tools like subscribe and unsubscribe. The verb+resource is specific and unambiguous.

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

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

The description provides explicit usage scenarios: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context, but it doesn't mention when not to use or name alternatives. It's well-directed but lacks exclusions.

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 the tool safe (readOnly, idempotent, non-destructive). The description adds valuable behavioral context by disclosing the effect of all_fields=true (returns names and descriptions instead of just IDs) and the default output behavior. This goes beyond 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 a single concise sentence plus a helpful tip about all_fields. Every word earns its place, and the main purpose is front-loaded.

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

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

Given the simple list operation and the presence of an output schema, the description covers the essential purpose and the non-obvious parameter behavior. It does not detail pagination, but the schema's limit/offset parameters suffice for basic understanding.

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 0%, so the description must compensate. It explains all_fields but does not explain limit or offset, though their names are relatively self-explanatory. Partial compensation is provided, so a middle score is appropriate.

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

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

The description clearly states the tool's function: listing Chilean government organizations from the datos.gob.cl CKAN catalogue. The verb 'list' and specific resource 'organizations' distinguish it from sibling tools like organization_show or group_list.

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 this tool is for listing organizations, but it does not explicitly state when to use it versus alternatives such as organization_show for detailed organization info. No exclusions or alternative tool references are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds context about the data source (Chilean CKAN catalogue) and the include_datasets option, but does not disclose error behavior or operational quirks, which is acceptable given the annotation coverage.

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, front-loaded sentence that names the data source and immediately states the tool's purpose and key parameters. Every word adds value with no redundancy.

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

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

For a simple show tool with only 2 parameters, an output schema, and strong annotations, the description covers the essential context: what it does, the optional subscription toggle, and the source. It doesn't need to explain return values because an output schema exists.

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

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

Schema coverage is 0%, so the description must compensate. It explains that 'id' is the organization identifier and 'include_datasets' toggles the list of datasets. It does not specify the exact format of the ID, but examples in the schema provide reasonable context. This is good compensation for the schema gap.

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 a 'full profile for a publishing organization by ID', listing name, description, and optionally datasets. This distinguishes it from siblings like organization_list and group_show, which serve different resource types.

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 the tool is for looking up a single organization by ID but provides no explicit when-to-use guidance or alternatives. It does not state when not to use it, such as when you need a list of all organizations (organization_list).

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

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

Annotations declare read-only, idempotent, non-destructive behavior. The description adds value by noting the paginated nature and that it returns slugs/names, which is useful beyond annotation hints. No contradictions found.

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

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

Two sentences, front-loaded with the key purpose and context, and no filler. Every word 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?

The tool is simple, has strong annotations, and an output schema. The description covers domain, purpose, and relationship to sibling package_show, which is sufficient for a paginated enumeration 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 0% and the description does not explain the limit/offset parameters beyond implying pagination. The terms are standard but the description fails to detail their semantics or defaults, leaving compensation gaps.

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

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

Description clearly states the tool lists all dataset slugs/names with pagination, specifying the Chilean data catalogue context. It distinguishes itself from siblings by explicitly positioning it as an enumeration step before package_show.

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

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

Provides explicit usage guidance: 'Use to enumerate available datasets before fetching details with package_show.' This names the alternative and clarifies when the tool is appropriate, fulfilling the dimension's requirement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds only 'full-text + faceted search,' which does not disclose behavioral traits like pagination, rate limits, or result handling. It adds minimal context beyond 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?

At three words, the description is extremely concise and free of fluff. However, it is under-specified for a tool with six parameters, making it concise at the expense of informativeness.

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 six-parameter schema with zero descriptions and no guidance in the description, agents cannot determine how to construct queries, what sort/facet options exist, or how pagination works. The output schema covers return values, but the description fails to compensate for the missing parameter semantics and usage context.

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

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

Schema coverage is 0% and no parameter descriptions are provided. The phrase 'full-text + faceted' offers a weak hint that q maps to full-text and facet_field maps to faceted search, but rows, start, sort, and fq remain entirely unexplained. The examples in the schema show usage but not semantics.

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 identifies the tool as a search with full-text and faceted capabilities, but it does not explicitly state what is being searched (packages). This makes it distinct from a tautology but still vague about the resource and scope, especially compared to siblings like package_list or package_show.

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?

No guidance is given on when to use this tool versus alternatives such as package_list, package_show, or search_within. There is no mention of context, prerequisites, or exclusions, leaving agents to infer 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=true, idempotentHint=true, and destructiveHint=false, so the description's additional context about the CKAN source and the contents of the metadata adds value beyond the annotations. It stops short of disclosing rate limits or error behavior, but given the rich annotations, this is acceptable.

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, front-loaded sentence that begins with the source and purpose, then lists the metadata fields. Every word contributes 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?

This is a simple one-parameter tool with annotations covering safety and an output schema available. The description provides enough context about the tool's niche and parameter semantics to enable correct 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?

With zero schema description coverage, the description compensates by explicitly stating that 'id' accepts a dataset ID or slug, which aligns with the example and clarifies the parameter's meaning beyond the bare string type.

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

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

The description clearly states that this tool retrieves full metadata for a dataset by ID/slug, and enumerates the included fields. It differentiates from sibling tools like package_search and package_list by emphasizing metadata completeness for a single 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?

The description implies the intended use case (getting detailed metadata for a specific dataset), but does not explicitly contrast it with alternatives such as package_search or package_list. The context is clear, though no exclusions are stated.

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

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

Annotations provide only generic flags (readOnlyHint false, etc.), but the description adds substantive behavioral context: rate limiting ('5 per identifier per day'), no quota cost ('free; doesn't count against your tool-call quota'), the claim_token workflow for read-back, and team response cadence ('reads digests daily and signal directly 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?

The description is long but every sentence earns its place. It front-loads the purpose, then covers usage triggers, scope exclusions, message guidelines, token follow-up, review cadence, and rate limits without redundant or filler text. The structure flows logically from intent to constraints.

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

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

With no output schema, the description takes on the burden of explaining results: it discloses that filing without an account returns a claim_token and how to use it to read status changes. It also covers all notable constraints (type enum, context structure, message length, rate limit, scope boundary). Given the tool's complexity, this is complete.

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

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

Although schema covers all 4 params, the description enriches meaning: it explains the claim_token is used to retrieve earlier feedback ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), what context should reference (pack/tool/vertical), and how message should be concise ('1-2 sentences typical'). This goes beyond the schema's definitions and integrates the parameters into a workflow.

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 immediately states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the exact resource (Pipeworx team) and scope ('ONLY for tools served by this Pipeworx connection'), distinguishing it from sibling tools. The three feedback categories (bug, feature/data_gap, praise) make the purpose and boundaries explicit.

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 the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also tells users how to frame feedback ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and how to follow up on a token.

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, idempotent), the description adds valuable context: it's a self-aggregating signal derived from CF analytics-engine, contains no PII, returns only (pack, tool, count) tuples, and is cached 5min-1h depending on window. This enriches the safety and freshness profile.

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

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

The description is concise and front-loaded. The opening sentence immediately explains what the tool returns, followed by a clear list of use cases and two succinct sentences on data source, privacy, and caching. Every sentence earns its place with no fluff.

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

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

For a single-optional-parameter, read-only tool with no output schema, the description is complete. It covers return values (top tools, top packs, total call volume), parameter semantics, use cases, caching behavior, and data provenance. Nothing significant is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds interpretive meaning for the 'window' parameter: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the enum literal descriptions, providing guidance on choosing between 24h, 7d, and 30d.

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 what the tool does with a specific verb and resource: 'Returns the top tools, top packs, and total call volume over a recent window.' It distinguishes itself from siblings like discover_tools by focusing on aggregate trending signals from other AI agents.

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

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

Provides explicit use cases in a numbered list: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It doesn't mention when-not-to-use or alternative tools, but the 'Useful for' section gives clear context for when to invoke this tool.

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

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

The description adds substantial behavior beyond the readOnlyHint/idempotent annotations: output shape, Jaccard similarity threshold, placeholder filter, and the fill check with realizable_edge_pp guidance ('do not trade it'). This gives an agent deep understanding of edge cases and how to interpret results.

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

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

The description is long but well-structured, front-loading the core purpose and using all-caps headers for key concepts. It could be trimmed slightly without losing value, but every section contributes necessary behavioral detail for a complex tool.

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

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

With no output schema, the description compensates by detailing the response structure for both modes, the fill check, and the null-arb condition. It also covers semantic anchoring and placeholder filters, making the tool's behavior fully specified 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?

Despite 100% schema coverage, the description enriches each parameter with concrete examples, mode-specific behavior, and processing details (e.g., event walks child markets, topic searches related events). It also explains semantics like the partition sum and cross-event patterns, exceeding the schema-level definitions.

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

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

The description states the tool 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', using a specific verb and resource. It clearly distinguishes three invocation modes (default trending scan, event, topic) and even differentiates from polymarket_fill_risk for custom sizing.

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

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

The description explicitly explains when to call with no args, with `event`, or with `topic`, and provides a recommendation: 'event (recommended for a specific market)'. It also names the alternative for custom sizing (polymarket_fill_risk), giving clear decision context.

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

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

Despite having annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description goes far beyond them: it discloses caching behavior (1h at KV level), the Kelly cap at 0.25, the 24h-move warning, and the design quirk that partition arbs return kelly_fraction_half=0 at parent level. It also explains the placeholder-slug filter and why Fed signals are excluded. No contradiction with annotations.

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

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

The description is a dense wall of text but is front-loaded with a clear purpose and uses ALL-CAPS segment names to aid scanning. Every sentence carries substantive info, though it could benefit from bulleted structure or shorter sentences to improve readability. It is appropriately sized given the tool's complexity.

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

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

There is no output schema, so the description fully carries the burden of explaining return values. It details the top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.). It also covers edge cases like empty segments via filter_skips, making the description nearly complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant parameter nuance: it clarifies that min_kelly never filters partition arbs, that min_partition_leg_kelly applies to per-leg Kelly, and that slippage_pp is subtracted from raw edge. The 'tradeable-edge knobs' phrasing ties parameters to their purpose, which the schema descriptions alone lack.

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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes itself from siblings by focusing on edge discovery across three named segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) rather than arbitrage or fill-risk 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 states its intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides extensive guidance on knobs and filters (e.g., min_liquidity/max_spread_pp to ensure tradeable edges), but does not explicitly name alternative tools for other scenarios, leaving some ambiguity about when not to use it.

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive hints, so the bar is lower, but the description adds rich behavioral context: snapshots written on cache-miss, gaps mean no scan that day, history bounded by 60-day TTL, decay computed on daily closes, and edge_pp_net is signed by trade direction. These nuances are not deducible from annotations and are crucial for correct interpretation of the response.

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

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

The description is long but well-structured with labeled sections (Args, RESPONSE, LIMITS) and front-loaded with the core purpose. Every sentence provides meaningful information about behavior, return semantics, or limitations. It is not wasteful, but the density of details (especially in the RESPONSE section) could be slightly overwhelming; still, each part earns its place.

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

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

There is no output schema, so the description must fully explain return values, and it does: tracked[], expired[], and snapshot_dates[] are all defined with key sub-fields (trend, decay_pp_per_day, lifespan_days, etc.) and their interpretations. It also covers data availability limitations (TTL, snapshot gaps) and computation basis (daily closes, net slippage). For a telemetry tool of this complexity, the description is complete and self-sufficient.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description goes slightly beyond by explaining that 'days' is a lookback with default 14, and 'window' selects the snapshot family ('1wk'), tying it to the polymarket_edges window families. It also notes max 30 vs schema clamp 2-30, adding practical context. Not a 5 because the schema already covers defaults and ranges; the description adds only modest interpretive value.

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

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

The description opens with a specific verb phrase: "Edge persistence and decay telemetry built from daily polymarket_edges snapshots." It then states the exact question it answers: "how long has this edge existed and is it shrinking?" This clearly distinguishes it from sibling tools like polymarket_edges by focusing on historical persistence/decay rather than current edge values.

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 implies usage context: use this tool when you need to understand edge persistence over time from snapshots, not for current edge values. It mentions it is built from polymarket_edges snapshots, which hints at the alternative (polymarket_edges) but does not explicitly say 'for current edge values use X.' The LIMITS section provides constraints on when results are meaningful (TTL, snapshot gaps), which helps with interpretation. No explicit exclusions or alternatives are named, so not a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses detailed behavior: it 'walks the ladder', returns fields like vwap_fill_price, slippage_pp, thin_legs[], and forced_directional_risk, and warns about the dominant loss mode. This adds substantial operational context without contradicting 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 long but well-structured: it front-loads the purpose and the critical 'REQUIRES' constraint, then details each mode and its outputs. While some redundancy with the schema exists, the length is justified by the tool's complexity and the actionable risk warning.

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

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

With no output schema, the description fully compensates by enumerating all return fields for both modes (top_of_book, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, etc.). It also covers edge cases like partial fills and forced directional risk, giving an agent sufficient context to invoke and interpret results correctly.

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

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

Although schema coverage is 100%, the description enriches parameter meaning significantly. It states 'REQUIRES one of market or event' (not captured in schema's required list), interprets size_usd differently for buys vs sells and single vs basket modes, and explains side defaults ('default auto from partition sum'). This goes well beyond the baseline.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges as tools it should precede, and explains its two modes.

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

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

It explicitly 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' and explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk). It also clarifies when to use market vs event mode.

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

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

The description discloses extensive behavioral details beyond annotations: compatibility_warning logic (two distinct cases), temporal_alignment consequences, skipped_cross_type/subtype counters, and the rareness of real cross-venue spreads. It enriches the readOnlyHint by describing what the tool reports when no valid spread exists.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries substantive information about behavior, limitations, or response structure. While not as concise as a two-line description, the complexity of the tool justifies the length.

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

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

Given that there is no output schema, the description fully explains the response format (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counts). It covers all critical contexts and edge cases for a tool with 3 optional parameters and high complexity.

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

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

The input schema already describes each parameter with examples. The description adds meaning by explaining the interaction between topic mode and explicit overrides, and by listing valid macro shortcuts. It goes beyond the schema's basic descriptions to clarify mode semantics.

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

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

The description clearly states the tool's function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses a specific verb ('spread') plus resource (Polymarket–Kalshi) and differentiates from sibling tools by emphasizing 'cross-venue' and the equivalence condition for meaningful delta.

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

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

The description explains two usage modes (topic shortcuts vs explicit tickers) and provides context about when results may be unreliable (compatibility_warning scenarios, temporal misalignment). It does not explicitly name alternative tools, but the warnings serve as clear 'when not to use' signals, e.g., 'pre-mapped ≠ tradeable'.

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond that: the scoping mechanism ('anonymous IP, BYO key hash, or account ID') and the dual-mode behavior of omitting the key to list all keys. This enriches the behavioral picture 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 three sentences long, with the primary action front-loaded. Every sentence adds value: the action, the use case, and the scoping/pairing context. No filler or 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 simplicity (one optional parameter, clear annotations, no output schema), the description covers all essential aspects: what it does, when to use it, how the key parameter behaves, and how scoping works. It is fully self-contained for an agent to select and invoke 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% and the parameter description already explains the key. The description adds semantic context by linking the key to values saved via 'remember' and giving concrete examples (user's target ticker, address, research notes). This clarifies the nature of the stored values beyond the schema's generic 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's specific actions: 'Retrieve a value previously saved via remember, or list all saved keys'. It uses a specific verb ('Retrieve') and resource ('value previously saved'), and distinguishes itself from sibling tools by explicitly pairing with 'remember' and 'forget'.

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

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

The description provides clear context on when to use: 'Use to look up context the agent stored earlier… without re-deriving it from scratch' and mentions scoping. It implicitly distinguishes from alternatives by naming 'remember' and 'forget' as complementary tools, but doesn't explicitly say 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?

The description explicitly describes a state-changing side effect (mark_read flags returned events read, affecting the next call) that contradicts the readOnlyHint=true annotation. Per the rubric, this is an annotation contradiction, forcing transparency to score 1.

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

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

Four sentences, front-loaded with the core purpose, then return format, filtering, and alternative access. Every sentence earns its place with no filler or 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?

Despite the annotation contradiction, the description covers purpose, return payload, filtering, mark_read behavior, polling suitability, and an alternative programmatic endpoint. Given no output schema and five optional parameters, this is remarkably 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 meaningful context beyond the schema: an example type ('sec_8k'), ISO timestamp semantics for since, and the behavioral impact of mark_read. This enriches parameter understanding.

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

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

The description clearly states the tool pulls fired events from the subscription feed using a specific verb and resource. It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on alerts with source, citation_uri, and raw payload.

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 clear context for when to use: polling alerts with optional type/since filters and mark_read. It also mentions an alternative GET endpoint for scripts/dashboards, but does not explicitly exclude sibling tools, so it lacks full when-not guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral traits: it fans out to multiple sources in parallel, documents a fallback chain (GDELT→GNews), and reveals a known soft-fail for USPTO due to API sunset in May 2025. It also states the return structure (changes[], total_changes, citation URIs). This is rich, honest behavioral context.

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

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

The description is dense but every sentence adds value: examples, core definition, data source breakdown, fallback logic, parameter details, return format, and an explicit alternative. It is front-loaded with the core purpose and avoids fluff, making it highly efficient for an agent to parse.

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

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

Given the tool's complexity (multiple data sources, fallbacks, no output schema), the description is exceptionally complete. It covers the return shape (changes[], total_changes, citation URIs), the behavior of the `since` parameter, source-specific behavior including a known failure mode, and references an alternative tool. No critical aspects are left unexplained.

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

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

The input schema already provides full descriptions for all three parameters (type, since, value), including accepted formats and examples. The tool description adds little beyond restating the `since` format and giving usage context. With 100% schema coverage, the baseline score of 3 is appropriate; the description does not substantially exceed what the schema offers.

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 change feed for a company over a recent window, with example query patterns and explicit source details (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from the sibling tool entity_profile by stating when to use each. This is a specific, well-scoped purpose statement.

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

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

The description provides explicit when-to-use guidance through natural language examples and clarifies when NOT to use it: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also specifies preferred usage of the `since` parameter ('Use "30d" or "1m" for typical monitoring').

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

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

The description adds behavioral details beyond the annotations by specifying pagination via limit/offset and the ordering by creation/update recency. Annotations already cover read-only, open-world, idempotent, and non-destructive characteristics, but the description supplements with useful operational context.

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

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

The description is two sentences long, with the core purpose and context front-loaded, followed by a concise usage note. Every phrase adds value with no redundancy.

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

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

The tool is simple with only two optional parameters and an output schema, so the description covers the essential aspects: the data source, what is returned (recently changed datasets), pagination, and the intended monitoring use case. It does not need to describe return values because an output schema is present.

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

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

The schema description coverage is 0%, so the description must compensate. It mentions 'paginated by limit/offset,' which indicates the parameters are for pagination, but it does not explain their individual meaning, defaults, or behavior when omitted. The examples in the schema provide some structure, but this is a partial compensation at best.

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

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

The description states the tool lists datasets most recently created or updated, identifying the resource (datasets) and the specific action (listing recent changes). It also names the source (Chilean open data catalogue/CKAN) and includes a usage purpose, distinguishing it from sibling tools like package_list or recent_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 explicitly says 'Use to monitor Chilean government open data activity,' giving a clear when-to-use context. It does not mention alternatives or exclusions, but the intended scenario is evident.

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 show idempotentHint=true and non-destructive. Description adds persistence context (authenticated vs anonymous sessions) and key-value scoping, which goes beyond annotations. No contradiction.

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

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

Three sentences, all necessary. Efficiently covers purpose, usage, persistence, and related tools without redundancy.

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

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

For a simple write tool with no output schema, the description fully covers usage scenarios, persistence behavior, and integration with recall/forget. No missing 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%, so parameters are already documented. Description provides conceptual context ('key-value pair') and examples, but doesn't add syntax or format details beyond what schema already offers.

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

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

Description starts with 'Save data the agent will need to reuse later' — specific verb+resource. It distinguishes from siblings by naming recall and forget, and gives concrete examples of what to store.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with examples. Also guides to alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing internal behavior: cascading through multiple lookup endpoints, graceful degradation if GLEIF/OpenFIGI are unavailable, explicit labeling of identifier sources, and stating unresolved identifiers explicitly. No contradiction with annotations.

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

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

The description is front-loaded with example queries and includes structured details within parentheses. It is verbose but every sentence adds value. Minor deduction for length, but it remains well-organized and readable.

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

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

Despite no output schema, the description fully explains what the tool returns: identifiers with source labels, unresolved entries explicitly listed, and the ability to handle multiple input types. It covers all important aspects for agent decision-making, making it contextually 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 meaning beyond the schema by revealing that 'value' can accept ISINs and company names (the schema only mentions ticker, CIK, or name for company). It also explains how ISINs resolve via GLEIF, which is not in the schema. This extra context earns a 4.

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

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

The description uses specific verbs like 'resolve' and clearly states the tool's function: converting user-spoken names to canonical/official identifiers. It lists example queries and explicitly distinguishes itself from sibling tools by noting it 'replaces 2-3 manual lookups.' The supported entity types and identifier sources are detailed, making the purpose unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also gives concrete examples of queries that trigger this tool. However, it does not explicitly state when not to use it or mention alternatives, though the context of 'first' implies priority.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the data source (datos.gob.cl CKAN) and the specific metadata fields returned, which is beyond 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 a single, dense sentence that front-loads the key context and provides all necessary information without waste. It is concise and 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?

The description covers the tool's purpose, input, and output fields effectively. It could mention error handling or explicit limitations, but for a simple read-only operation with an output schema, it is adequate.

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

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

The schema has no descriptions for the single 'id' parameter, and the description clarifies that this ID is a resource ID. This is essential for distinguishing it from package or group IDs, though it doesn't specify the expected format.

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 ('metadata for a single resource') and clearly identifies the resource type and catalogue. It lists the returned fields, which distinguishes it from sibling tools like package_show and group_show.

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 that this tool is for retrieving metadata about a specific resource using its ID, but it doesn't explicitly state when to use it over related tools like package_show or organization_show. No exclusions or alternatives are provided, though the naming makes the distinction fairly clear.

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

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

Annotations already cover the safe operation (readOnly, idempotent), and the description adds meaningful behavioral detail: it performs N+1 probes (your brand + N competitors), ranks by score, and returns a ranked list with score, confidence, and signal density. It does not mention potential rate limits or API key requirements, but the added context goes beyond the annotation defaults.

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 at three sentences, front-loaded with the core action ('Compare AI visibility...'), and each sentence adds value: action, mechanism, use case, and return value. No filler or repetition of schema details.

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

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

Since there is no output schema, the description explicitly states the return format: 'ranked list with score, confidence, signal density per entity.' Given moderate complexity (4 params, 1 required) and a clear schema, this is sufficiently complete for an agent to select and invoke 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% and the schema already documents each parameter, including the special role of the first entity as 'subject'. The description adds no new parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Compare' and identifies a clear resource 'AI visibility across multiple entities side-by-side'. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by clarifying the ranking and competitive context.

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

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

The description provides clear context by stating it is 'Useful for competitive AI-marketing audits' and explains it probes each entity with ai_visibility_check, which implies when to use this over a single-entity check. However, it does not explicitly name alternatives or state when not to use, so it stops short of full exclusion 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?

Discloses behavioral traits beyond annotations: returns a summary block with specific fields, per-advisory details, and links; partial failures degrade gracefully; bundlephobia's first measurement can take 5-30s and sources_failed will list it. No contradiction with readOnly/idempotent hints.

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?

Although longer than typical, every sentence is information-dense: composite action, use cases, return fields, ecosystem limits, failure behavior. Front-loaded with purpose, no filler.

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

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

Given no output schema, the description fully explains return fields, ecosystem scope, and timeout/failure behavior. It includes enough context for an agent to invoke correctly and interpret results.

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

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

Schema covers 100% of parameters with clear descriptions (package name, optional version defaulting to latest). The description adds no new parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states it is a composite 'should I add this npm package to my project' check that fans out to deps.dev and bundlephobia. Specific verb ('check'), resource ('npm package'), and scope, distinguishing it from package_list/search/show siblings.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes that non-NPM ecosystems should use deps.dev:version directly. This provides clear when-to-use and alternatives.

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

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

Annotations already declare readOnly and idempotent, but the description goes far beyond: it discloses the embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), response contents (passages with offsets and scores), and the 200K char truncation behavior. This is rich, non-contradictory behavioral context.

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

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

The description is longer than average (four sentences), but every sentence earns its place: purpose, use case, pairing, and technical mechanics. It is front-loaded with the core action and progressively adds implementation detail, though a minor redundancy ('passages that matter' and 'top-N passages') could be trimmed.

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

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

Despite lacking an output schema, the description explains exactly what the agent gets back (top-N passages with character offsets and similarity scores), plus the truncation flag. It covers input size limits, pairing with grounded workflows, and the technical search mechanism, making it fully self-sufficient for a tool of this complexity.

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

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

Schema covers all parameters at 100%, so baseline is 3. The description adds meaningful context beyond the schema: it defines 'text' as 'the text you already pulled' with concrete examples (SEC 10-K, article, long tool result), clarifies query as a natural-language request with examples, and explains limit via 'top-N passages'. This elevates parameter understanding.

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

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

The description opens with 'Semantic search INSIDE a fetched record', clearly specifying the verb (semantic search), resource (fetched record), and scope (inside it). It distinguishes itself from siblings by contrasting with ask_pipeworx_grounded and explaining the workflow pairing, making its unique role unmistakable.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Names the alternative/companion ask_pipeworx_grounded with a clear workflow, but does not explicitly state when not to use it (e.g., for small records), so it falls just short of full 5.

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

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

Annotations already provide readOnlyHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond annotations: it specifies authentication requirements (OAuth account), the always-on feed behavior, phone verification for SMS, and the 10/day cap. It does not contradict any annotation, though it could have elaborated on the idempotency semantics.

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

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

The description is front-loaded with the core purpose, then compactly lists subscription types and delivery channels without redundant filler. However, the second sentence is a dense run-on that mixes types, parameters, and delivery details, making it slightly harder to parse than an ideal structured summary. It earns high marks for no waste but loses a point for readability.

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

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

Given the tool's complexity (multiple types, delivery channels, auth requirements), the description covers the main decision points: what types exist, what params are needed, and how delivery works. It omits webhook from the main description (though schema covers it) and does not explain idempotency or return format beyond the id. Still, with full schema coverage, it is complete enough for an agent to select and use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by attaching concrete semantics to parameters: e.g., items:['5.02'] = officer change for sec_8k, and polymarket_edge is described as cross-venue mispricings. These enrich the bare parameter examples in the schema, helping the agent understand the functional impact of choices.

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 opens with 'Create a proactive monitoring subscription to a live-data event stream,' clearly stating the verb (create), resource (subscription), and purpose (monitoring). It distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and explicitly noting that the feed can be pulled via recent_alerts, making the tool's unique role unambiguous.

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

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

The description provides clear context on when to use the tool: it requires a Pipeworx OAuth account, so anonymous/BYO users should not use it. It also explains that the feed is always on and can be pulled via recent_alerts without subscribing, implying that subscribe is needed for proactive channels like email or SMS. While it doesn't explicitly say 'use this instead of X,' it gives enough contextual guidance to differentiate from alternative actions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: the tool returns category-bucketed example questions with exact tool+argument shapes, drawn from the live catalog, and supports both full-spread and topic-focused calls. 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 front-loaded with realistic user queries and packs useful detail into a single paragraph. It is somewhat long and run-on, listing many categories inline, but every part serves a purpose—clarifying scope, output content, and invocation variants. Minor structural improvements could make it scannable, but it remains efficient for the information conveyed.

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 is fully complete: it states what it returns, the categories covered, how the optional parameter alters behavior, and how this tool fits into the broader tool ecosystem. The annotations and schema round out the safety and parameter details, leaving no significant gaps.

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

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

Schema coverage is 100% for the single optional 'topic' parameter, but the description enriches this by listing concrete examples ('finance', 'pharma', 'betting') and the full category list. It also explains the behavior when the parameter is omitted, which goes beyond the schema's plain 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 identifies this as the onboarding entry point for an agent that just connected, listing the exact user intents it handles ('what can I ask Pipeworx?', 'getting started', 'give me ideas'). It distinguishes itself from sibling tools by explicitly stating to use it FIRST and positioning it as a gateway to meta-tools like ask_pipeworx, entity_profile, and compare_entities.

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

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

The description gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains optional topic filtering and no-args usage. However, it doesn't mention when not to use it or directly contrast with the sibling discover_tools, though it implies primacy.

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 convey read-only, idempotent, non-destructive. The description adds the scope (all tags, optionally filtered) and the CKAN context, which is useful behavioral insight beyond 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?

Two sentences with no waste. First sentence states purpose, second gives usage guidance. Front-loaded and efficiently 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?

For a read-only list tool with rich annotations and an output schema, the description covers the main purpose and usage. However, it misses explanations for two parameters, so it is not fully complete for agents needing to set all fields.

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 0%, so the description carries full burden for explaining parameters. It only addresses 'query' via 'filtered by query string', leaving 'all_fields' and 'vocabulary_id' entirely undocumented. This is insufficient for a 3-parameter tool.

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 lists all dataset tags from the Chilean CKAN catalog, with optional query filtering. It distinguishes from sibling tools like package_search or group_list by focusing specifically on tags.

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 it: 'Use to browse taxonomy before filtering package_search by tag.' This provides both the use case and an explicit alternative (package_search), fulfilling the when-to-use vs alternatives requirement.

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

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

Adds significant behavioral detail beyond annotations: ownership enforcement, soft-deactivation (row not deleted), and that historical events remain accessible via recent_alerts. This clarifies the non-destructive nature and post-cancellation behavior, which annotations don't cover.

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

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

Three concise sentences with no fluff. The first sentence front-loads the primary action, and the following sentences add necessary context without redundancy.

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

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

For a simple single-parameter tool, the description covers the action, ownership requirement, and the soft-delete behavior with downstream impact. It is complete and sufficient for an agent to understand use and consequences.

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

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

The schema already fully describes the parameter as a uuid returned by subscribe (100% coverage). The description adds the ownership context but no additional technical detail for the parameter itself, so baseline 3 applies.

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

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

The description uses a specific verb 'Cancel' with a clear resource 'subscription' and specifies the operation is by id. It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions' by stating the action is cancellation.

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 clear context that ownership is enforced and only your own subscriptions can be canceled. It also notes the consequence for historical events, but does not explicitly mention alternative tools or 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals critical behavioral traits: the semantic difference between could_not_verify (check did not happen) and unsupported (no source found), the internal routing to SEC EDGAR versus the grounded pipeline, and the use of 'verbatim evidence' and 'exact percent-delta math.' It also warns callers not to treat could_not_verify as evidence, which is essential for correct output interpretation.

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

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

The description is appropriately sized for the tool's complexity, using examples, a clear routing explanation, a return-verdict list, and an important error-semantics callout. Every sentence adds value, and the structure is front-loaded with the core purpose and trigger phrases, making it 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?

Given the tool's complexity (routing, multiple verdicts, error semantics) and the absence of an output schema, the description is remarkably complete. It covers inputs, outputs, error cases, source routing, and efficiency benefits, leaving no critical ambiguity for an agent deciding whether and how to invoke it.

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

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

Schema description coverage is 100% for both parameters (claim and tolerance_pct), so the baseline is 3. The description itself does not add significant parameter-level detail beyond what the schema already provides, though it does mention tolerance indirectly through the approximately_correct verdict. No contradiction or gap requiring extra compensation.

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 opens with trigger phrases and states 'natural-language claim verification against authoritative sources,' naming the specific verb ('verify') and resource ('claims'). It distinguishes itself from sibling tools by emphasizing fact-checking with verdicts and the structured SEC EDGAR fast path for financial claims, clearly differentiating from general grounded Q&A tools like ask_pipeworx_grounded.

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

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

The description explicitly directs use 'whenever the agent needs to check whether something a user said is factually correct' and explains the routing between company-financial claims and other factual claims. It also notes the tool replaces 4–6 sequential calls, implying efficiency. However, it does not name specific alternative tools or provide explicit 'when not to use' exclusions, though the context is otherwise clear.

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