Podatki Si

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 annotations: default model (Workers AI Llama-3.3-70b), optional Anthropic probing with a BYO key (including direct payment), and the return structure. This covers auth needs and expected output, though it omits rate limits or error conditions.

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

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

The description is three sentences, front-loaded with the core function in the first sentence. Every sentence contributes essential information (function, model details, output and use cases) 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?

Given the tool's complexity (4 params, optional model selection, API key handling) and the absence of an output schema, the description adequately covers the return format (per-model {score, confidence, signals, raw_response} + combined view), default behavior, and use cases. It provides enough for 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?

Schema description coverage is 100%, so parameters are already well-documented. The description adds extra meaning by specifying the default model name ('Workers AI Llama-3.3-70b') and clarifying the _apiKey is for Anthropic with direct payment, which goes beyond the schema's basic 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 starts with a specific verb ('Probe') and resource ('one or more LLMs'), clearly stating the tool's function of scoring visibility (0-100). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on general AI visibility across multiple models, making the purpose unambiguous.

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

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

The description explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context for when to use it. However, it does not mention alternatives or cases where another tool might be more appropriate, lacking explicit 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?

Beyond annotations (readOnly, openWorld, idempotent), the description reveals behavior: routes to 5,462 tools, returns 'stable pipeworx:// citation URIs', handles live news and breaking topics, and works on every tier as a single fast call. 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 longer than average but well-structured and dense with valuable information. It front-loads the primary purpose, then gives examples and escalation paths. Every sentence earns its place, though a slightly tighter phrasing would push it to a 5.

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 explains return format (structured answer with citations), covers a wide range of question types, and provides concrete examples. It also addresses when to use alternatives, making the tool's context complete for an AI 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 input schema already documents all parameters (question plus aliases) with descriptions and examples. The description adds no extra parameter-level semantics beyond what the schema provides, but the schema coverage is 100%, 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?

The description clearly states this tool answers factual questions by routing to curated sources, with specific verb ('answers') and resource ('5,462 tools across 1419 verified sources'). It also distinguishes from siblings like ask_pipeworx_grounded and deep_research, making the unique 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?

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and gives criteria for alternatives ('Step up only when needed' for grounded or deep_research). Also lists use-case examples and trigger phrases, making the decision tree 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 read-only, idempotent, open-world, and non-destructive traits. The description adds valuable behavioral context by disclosing the beta state, that candidate routing improvements are only enabled under test, and that no candidate is currently active (retired on 2026-07-26). It further explains that results are compared for merges, giving the agent insight into the experimental nature 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, with each sentence contributing essential information: what the tool is, current status, usage directive, and reassurance that it is a full working router. It is slightly verbose but the extra detail is justified given the experimental nature of the tool and the need to differentiate it from the stable version.

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 key aspects an agent needs: tool identity, current state, usage guidance, and a reference to ask_pipeworx for response shape. While there is no output schema, the notation 'same response shape' directs the agent to the sibling tool for return format details. Given the strong annotations and schema, the description is sufficiently complete for safe 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?

The input schema provides 100% coverage, documenting the required 'question' parameter and five aliases (q, text, input, query, prompt) with descriptions. The description only adds 'same arguments' as ask_pipeworx, which is redundant with the schema. Since the schema already fully explains parameter semantics, the description doesn't need to add more; baseline 3 is appropriate.

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

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

The description clearly identifies ask_pipeworx_beta as a beta variant of ask_pipeworx, specifying it as an identical universal router with the same 5,462 tools, arguments, and response shape. This distinguishes it from the stable sibling tool and states its current behavior matches exactly. The verb 'ask' plus resource 'pipeworx_beta' is specific and purposeful.

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

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

The description explicitly instructs to 'use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. It also clarifies that this is a full working router with no fallback, reinforcing when it's appropriate to use. This provides clear when-to-use guidance and implicitly contrasts with the stable ask_pipeworx.

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?

Even though annotations already declare readOnly and non-destructive behavior, the description adds crucial behavioral details: it makes an extra LLM call, returns a structured refusal with specific refusal_reason values, and extracts answers only from tool results. These go well beyond the annotations and are not contradictory.

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 and dense with information, but every sentence serves a purpose: mode definition, mechanism+output, usage guidance, and cost tradeoff. It is slightly longer than the high-calibration example but well-structured and front-loaded.

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

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

The tool has no output schema, but the description fully specifies the success return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and failure modes with exact refusal_reason enumerations. It also covers cost, usage context, and alternatives, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with all aliases described in the input schema, so the description does not need to explain parameters. The description does not add extra parameter-level meaning beyond stating that it fills arguments, which is already implied by the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly contrasts it with ask_pipeworx by explaining the extraction protocol ('EXTRACTS the answer using ONLY what the tool result contains'). This specific verb and resource distinguish it from sibling tools.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists concrete high-stakes domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative: 'prefer ask_pipeworx for casual lookups.'

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 openWorldHint=true, but the description goes far beyond that. It discloses low-confidence short-circuit behavior, closed-market handling, wide-spread illiquidity flags, blocking behavior, the resolver contract requiring inspection before trust, and even a 'recursive pure-rules loss' warning about cancellation rules. This provides deep operational context that annotations cannot convey.

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

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

The description is long, but every section (RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) provides high-value operational detail that would otherwise be missing. It is front-loaded with the purpose and key use cases, then organized into labeled blocks. It earns its length, though it could be slightly tightened to reduce cognitive load.

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 carries the burden of explaining return values. It details result.market, result.analysis, result.evidence, result.market_match_confidence, parent_event fields, news fallback mechanism, status strings, and cancellation-rule parsing. Combined with the schema and annotations, this gives an agent everything needed to invoke and interpret 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 descriptions already cover the format for market, the depth enum values, and the include_raw trade-off. The description adds a bit of context (e.g., what fan-out depth implies and how to pass a market), but it largely restates or complements schema info. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input formats (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). It also distinguishes itself from sibling tools by focusing on holistic bet research, while siblings like polymarket_arbitrage or polymarket_edges target specific narrow 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?

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives fan-out examples across categories, implying when each path activates. However, it does not explicitly mention when NOT to use this tool or point to alternatives (e.g., for arbitrage use polymarket_arbitrage), 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it fetches specific metrics (10-K revenue, net income, etc.), handles off-calendar fiscal years (AAPL, NVDA), sorts results by primary metric, and returns paired data with citation URIs. This goes well beyond annotations.

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

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

The description is dense but efficient, front-loaded with trigger phrases and a clear purpose. Each clause adds useful information, but it's somewhat long and could be tightened without losing value. Still, every sentence earns its place.

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

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

Given only 2 parameters and no output schema, the description fully covers what the tool does, what it returns (paired data + URIs), and how results are presented (sorted by primary metric). It even mentions the efficiency benefit (replaces 8-15 lookups), making it 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?

Even though schema coverage is 100% (type and values well-described), the description adds significant detail: for type='company' it specifies exact financial metrics and fiscal-year handling; for type='drug' it lists FAERS counts, FDA approvals, and trial counts. It also clarifies that values must be tickers/CIKs for companies and drug names, supplementing the schema with real-world usage guidance.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with a specific verb ('compare') and resource. It includes various trigger phrases and explicitly differentiates from sequential single-pack lookups, making it distinct from sibling tools.

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

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

The description gives explicit when-to-use guidance: for comparison queries like 'X vs Y' and ranking, and states 'ALWAYS PREFER over sequential single-pack lookups'. It also clarifies the two entity types (company/drug) and what data each pulls, providing clear context for appropriate use.

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

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

The description adds value beyond the annotations by specifying the output includes 'all resources and their resource_ids', which clarifies the scope of the returned data. The annotations already indicate a safe, read-only, idempotent operation, so the description's additional detail about resource IDs is useful contextual behavior.

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

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

The description is a single, clearly structured sentence that front-loads the purpose ('Show full metadata') and directly states the key details. No redundant or extraneous words are present.

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

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

For a tool with one parameter, no output schema, and clear annotations, the description sufficiently covers what the tool does, how to invoke it, and what the response includes. The reference to search_datasets provides enough workflow context for an agent to use it effectively.

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

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

Schema description coverage is 100% with the 'id' property already explained as 'Dataset id or name (from search_datasets)'. The description repeats this same information without adding additional semantic detail, so it meets the baseline but does not enhance parameter understanding beyond the schema.

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

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

The description clearly states the action ('Show full metadata') and the resource ('one Slovenia Open Data dataset') with an explicit lookup method ('by id or name'). It distinguishes itself from sibling tools like search_datasets and query_resource by specifying it returns complete metadata including resource_ids.

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 contextual usage by noting the id/name comes from search_datasets, implying a typical workflow of searching first then retrieving details. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 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?

While annotations already convey readOnly, openWorld, idempotent, and non-destructive traits, the description goes far beyond: it discloses account/plan requirements, decomposition and parallel routing to 5,462 tools, the return format (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] and contradictions[], citation_uri fetchability, semantic excerpting behavior, and latency expectations. This richly contextualizes what the agent will experience when invoking the tool.

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 carries functional weight—auth requirements, purpose, alternatives, behavior, output details, and performance are all covered with no filler. It is front-loaded with the most critical operational constraint (ACCOUNT REQUIRED) before moving to usage semantics, and the density is justified by the tool's complexity.

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

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

With no output schema present, the description compensates by detailing the findings packet structure, citation format, gaps[] and contradictions[] fields, hop field, and excerpting behavior, making the return value predictable. It also covers edge cases (news topics, large records, multi-step questions) and performance, so an agent can decide confidently whether this tool fits the task and what to expect.

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 provides 100% coverage with enums for depth and a natural-language description for question, but the description adds critical semantics beyond the schema: it explains that 'standard' re-angles unanswered gaps, 'thorough' chases leads and is paid, and that broad/multi-part questions are acceptable. It also ties the depth parameter to time expectations ('15-60s', 'up to ~90s'), which the schema alone does not convey.

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 and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in 'ONE call', explicitly distinguishing it from open-web search and sibling ask_pipeworx. It also states what it is NOT ('this is NOT open-web search') and gives concrete examples ('compare X and Y's regulatory + financial exposure'), making the tool's 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?

The description gives explicit when-to-use and when-not-to-use guidance: use for broad/multi-part questions over structured data; use ask_pipeworx for single lookups, breaking current-news, or colloquial topics; and use ask_pipeworx if not signed in. It even names the alternative tool and explains why deep_research would fail on news topics (mostly empty gaps[]), which is exactly the kind of exclusion an agent needs.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes beyond this by explaining the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are immediately callable without a second schema lookup. This adds meaningful behavioral context not present in 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 well-structured: it opens with the core action, lists supported domains, explains the return value, and closes with a usage recommendation. Every sentence earns its place, and the content is dense without being verbose.

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

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

For a straightforward discovery tool, the description covers what the tool does, when to use it, what it returns, and gives examples. With no output schema, the description clearly explains the output structure. The rich annotations and schema fill in the remaining safety and parameter details, making this complete.

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

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

The input schema has 100% description coverage for all six parameters, including aliases and examples. The description does not add new parameter-level detail beyond what the schema already provides, so the baseline of 3 is appropriate. It does mention 'top-N' which implicitly ties to the 'limit' parameter, but that is minor.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task' and lists the specific domains it covers. This distinguishes it from sibling tools, which appear to be task-specific (e.g., bet_research, compare_entities, search_datasets) rather than a general discovery mechanism.

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

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

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available and want to see the option set.' This tells the agent when to invoke this tool and frames it as an initial discovery step.

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, which cover safety. The description adds valuable behavioral context: it fans out across multiple sources in parallel, mentions a specific fallback (GDELT→GNews), and discloses a patent API sunset with soft-fail behavior. This goes beyond basic 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 long but every clause carries functional weight: user-facing examples, alternative guidance, output contents, source list, and input constraints. It is front-loaded with natural language triggers and then proceeds into structured details. Slightly dense but not wasteful.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description covers the return payload thoroughly: CIK/name, filings with URIs, fundamentals fields, patents, news, and LEI. It also states the one unsupported input mode and how to work around it. Minor gaps like exact error handling or response format details prevent a 5.

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%: the schema already explains both parameters with examples and names-not-supported note. The description reiterates the same input rules but does not add any new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call', with multiple example queries. It distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and mentions alternatives like resolve_entity.

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

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

The description gives explicit when-to-use guidance: use when the user wants a holistic view of a company, and prefer over chaining single-source lookups. It also clearly states a key limitation — names are not supported, and advises using resolve_entity first when only a name is available.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds context that it deletes previously stored memory, which is consistent. It doesn't contradict annotations, and the 'clear sensitive data' purpose adds behavioral intent.

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

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

Two concise sentences, front-loaded with the action, no redundant information.

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

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

For a simple one-parameter delete tool with strong annotations, the description covers purpose, usage, and pairing. It doesn't specify return values, but that's not critical here.

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

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

Schema description coverage is 100% for the single 'key' parameter, and the description repeats 'by key' without adding new syntax or format details 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 states 'Delete a previously stored memory by key' with a specific verb and resource, clearly distinguishing it from sibling 'remember' and 'recall' 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?

Provides explicit when-to-use scenarios ('stale context, task done, clear sensitive data') and suggests pairing with remember/recall, but does not explicitly state when-not-to-use or alternative tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing that it fetches the page and extracts title/description/key links, plus the output format as a single text blob. This is useful context beyond annotations.

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

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

The description is three sentences with a clear hierarchy: main purpose, process, and use cases. Every sentence adds value and there is no fluff 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?

With only two well-documented parameters, no output schema, and strong annotations, the description sufficiently explains the tool's behavior, output, and typical applications. Nothing critical 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% for both parameters, so the schema fully documents url and max_links. The description does not add extra parameter details, meeting the baseline of 3 for high coverage.

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

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

The description explicitly states the tool generates a production-ready llms.txt file for any URL, which is a specific verb+resource combination. It clearly differentiates from sibling tools like scan_competitor_ai_presence or ai_visibility_check by emphasizing the file output and standard format.

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 concrete use cases: getting a client's site indexed, drafting for own project, or auditing competitor AI visibility. It does not explicitly name alternatives or when not to use it, but the use case list gives clear context for selection.

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. The description adds valuable context beyond annotations by specifying the scope (caller's subscriptions), the returned fields, and that it defaults to active subscriptions. No contradiction with annotations.

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

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

Two sentences, front-loaded with the verb and resource, and no unnecessary words. Clearly structured with purpose, return fields, and usage guidance.

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

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

Despite lacking an output schema, the description lists all returned fields, making the tool self-contained. The single optional parameter is documented in the schema, and the description gives context on when to use it. Complete for a simple read-only list 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 description coverage is 100%, with the include_inactive parameter fully documented in the schema. The description adds no parameter-specific details, but the schema already handles semantics, 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 the specific verb 'List' with the resource 'the caller's active subscriptions,' clearly stating what the tool does. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on the read-only listing of existing subscriptions.

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

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

Provides explicit use cases: use to review what you're monitoring before adding more, or to find an id to cancel. It does not explicitly name alternatives or when-not-to-use, but the context is clear and actionable.

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

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

All annotations are false, so the description carries the full burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), clarifies it is free and doesn't count against quota, and mentions that feedback affects roadmap. This goes beyond annotations and gives the agent practical expectations for invoking the tool.

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

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

The description is dense but well-structured, front-loading the primary purpose and then covering usage, exclusions, content expectations, and operational details (rate limit, quota). Every sentence contributes value, and the length is justified given the tool's many caveats.

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 and all annotations false, the description must be self-sufficient. It covers the full behavioral contract: what triggers each type, when not to use, content style, rate limits, and target audience. The tool is simple, and the description leaves no critical ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful guidance beyond the schema by instructing users to 'describe the issue in terms of Pipeworx tools/packs' and 'don't paste the end-user's prompt', which helps craft the message and context fields. This enriches the semantic understanding of parameters without being redundant.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the tool from siblings like ask_pipeworx or discover_tools, which serve different purposes (querying vs. providing feedback).

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data, when a tool you wish existed isn't in the catalog, or when something worked surprisingly well') and when not to use it ('ONLY for tools served by this Pipeworx connection' — otherwise file with that server). It also advises against pasting end-user prompts, providing clear alternatives and content guidance.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, etc.) by disclosing that the data is self-aggregating from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour. This provides meaningful behavioral context about data recency and privacy, which is particularly valuable for a read-only analytics tool.

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

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

The description is well-structured with the core purpose first, then use cases, then additional technical details. It is slightly longer than strictly necessary—the use case list is verbose—but each part adds value and the front-loading makes it easy to grasp quickly.

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, this description is highly complete. It explains what is returned (top tools, packs, call volume), the time windows, concrete use cases, data provenance, privacy, and caching behavior. An agent has sufficient understanding 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?

The input schema already fully describes the only parameter (window) with an excellent description including default and trade-offs. The main description reiterates the window options but adds no new semantic information beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it returns top tools, top packs, and total call volume on Pipeworx over a configurable window. The verb 'Returns' and specific resource ('what other AI agents are calling on Pipeworx') make the function unambiguous. It also distinguishes itself from likely siblings like discover_tools by focusing on aggregate trending usage rather than static listing.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment with agent needs), which is strong contextual guidance. However, it does not name alternatives or state when not to use the tool, so it falls short of the 'explicit when/when-not/alternatives' criterion for 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 only declare readOnly/openWorld/idempotent hints. The description goes far beyond by disclosing internal filters (semantic anchor with Jaccard threshold, partition placeholder filter), output structure, and the fill-check pricing behavior against CLOB depth. This is rich behavioral context well beyond the structured fields, and 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 long but front-loaded with the core purpose and uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to aid navigation. Some redundancy exists (partition_check is explained both inline and in the response structure), but nearly every sentence carries operational value 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?

Given the tool's complexity, two optional parameters, no output schema, and rich sibling landscape, this description is remarkably complete. It explains both modes, the mathematical checks, filter thresholds, response fields, and how to interpret the fill check—leaving the agent well-equipped 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%, so the baseline is 3, but the description adds substantial meaning: it explains what happens with each parameter (event walks child markets, topic searches related events), gives real slug/seed examples, and describes the computation performed on the union. This goes well 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 opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by naming the exact detection methods and explaining two distinct modes (event and topic) with concrete examples.

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

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

The description provides explicit when-to-use guidance: use `event` for a specific market and `topic` for cross-event scans, even recommending a preferred approach ('event (recommended for a specific market)'). It also tells users when not to trade ('realizable_edge_pp ≤ 0 ... do not trade it') and points to a sibling tool for custom sizing ('For custom sizing use polymarket_fill_risk').

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 discloses rich behavioral traits: 1-hour KV caching keyed on knobs, diagnostics to explain why segments are empty, the 24h-move warning, the Fed-bets exclusion note, placeholder-slug filtering, and the design decision that partition arbs return kelly_fraction_half=0 at parent level. This far exceeds the baseline expectation.

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

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

The description is information-dense but also quite long and densely formatted. It front-loads the purpose effectively, yet the extensive detail on model families (e.g., per-sport α values, exact gate thresholds from Run 8) may be more than an agent needs for invocation. While every sentence carries substantive content, the wall-of-text style makes it harder to parse quickly, so it is not optimally concise.

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

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

With no output schema, the description carries the full burden of explaining the response structure, and it does so thoroughly: by_segment with three model families, top-level fields like fed_candidates/fed_note, diagnostics with funnel counters, and edge attributes (edge_pp_net, kelly_fraction, liquidity, spread_pp). It also covers edge cases such as stale markets, placeholder filters, and caching behavior, making it complete for a complex tool.

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

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

While the schema already documents each parameter with descriptions (100% coverage), the description adds design intent and cross-parameter context. It explains that min_liquidity/max_spread_pp are 'tradeable-edge filters' that drop non-realizable opportunities, and that min_partition_leg_kelly applies per-leg because parent-level Kelly is zero for basket trades. This adds meaning beyond the schema's field-level explanations.

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+function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further clarifies the intended use case ('what should I bet on today') and differentiates itself from siblings by describing its model-family approach and response segmentation.

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

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

The description provides clear context for when to use the tool: it is designed for agents to discover betting opportunities without paging through hundreds of markets. It also explains the purpose of tradeable-edge knobs (min_liquidity, max_spread_pp) and diagnostics, implying how to filter results. It stops short of explicitly naming alternative sibling tools for other use cases, so a slight deduction applies.

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 annotations: snapshot TTL limits, cache-miss gaps, daily close-based decay computation, and detailed response semantics. Annotations only declare read-only, open-world, and non-destructive; the description enriches this with real-world data lineage and timing details.

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

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

The description is dense and informative, front-loaded with purpose and followed by response/limits. It is longer than average but every component (args, response, limits) serves a purpose especially given there is no output schema. Could be tightened slightly but remains efficient.

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

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

With no output schema, the description fully compensates by detailing tracked[], expired[], snapshot_dates[], trend values, decay_pp_per_day, lifespan_days, and TTL limitations. It covers edge cases like snapshot gaps and historical depth boundaries, making it complete for the tool's complexity.

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

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

Schema coverage is 100%: both `days` and `window` have descriptions in the schema. The description mostly reiterates defaults and adds the term 'snapshot family' but does not introduce novel parameter semantics beyond what the schema already provides. 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 the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges by focusing on historical persistence and 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?

The description provides clear context for when to use the tool, including a strategic rationale ('a fresh wide edge and a 3-week-old wide edge are different trades') and mentions that 'median lifespan is your competition clock.' However, it does not explicitly name alternatives or state when not to use it, 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond those hints: it 'walks the ladder', returns a verdict (clean|degraded|cannot_fill), and identifies 'forced_directional_risk' and 'thin_legs[]' to warn about partial fill risks. No contradiction with annotations.

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

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

The description is dense yet front-loaded: the core purpose appears in the first sentence, followed by a structured mode-by-mode breakdown and a direct usage directive. Every sentence earns its place, and the length is appropriate for the tool's complexity.

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

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

No output schema exists, so the description compensates by enumerating specific return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs[], max_clean_notional_usd). It also covers mode selection, parameter defaults, and the risk rationale, making the tool fully usable by an AI 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 already covers 100% of parameters with descriptions, but the tool description adds mode-dependent interpretations: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode versus 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also clarifies default side behavior and how market vs event selects the mode, enriching understanding beyond the schema alone.

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

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

The opening phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth' states a specific verb+resource. It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edges by framing the tool as a risk checker rather than a signal finder, and further details two distinct modes (single-market and basket).

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 when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' naming specific alternative tools and the precise conditions. It also explains why (theoretical overround on thin books is not capturable, partial fills convert arbitrage into unhedged directional risk).

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, open-world, idempotent, and non-destructive, so the safety profile is known. The description goes beyond by detailing compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type counters, plus the warning that most pre-mapped topics currently are non-tradeable, which is important 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 long but densely structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS), and every sentence adds necessary context about behavior and limitations. It is front-loaded with the core purpose, though it is a wall of text for quick scanning.

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

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

Without an output schema, the description explains the response fields (leg-by-leg prices, top_spreads_pp), safety fields, and temporal alignment, covering the tool's complexity. It also addresses edge cases where compatibility is invalid, which is essential for correct usage.

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

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

The schema already documents each parameter with descriptions and examples, covering 100%. The description adds mode-based semantics: topic selects from a pre-mapped list, while explicit tickers override the topic-mapped side, clarifying interaction behavior beyond the schema.

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

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

The description clearly states it computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb and resource. It distinguishes from sibling Polymarket tools by explicitly naming the two venues and the cross-venue nature.

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 describes two modes (topic shortcuts vs explicit tickers) and when to use each, and warns that pre-mapped topics often return compatibility warnings, implying when not to expect tradable spreads. It does not explicitly name alternative sibling tools, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the useful constraint that only DataStore-enabled resources are queryable, which is valuable context. However, it does not disclose behavior such as error handling or response format beyond 'pull rows'.

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

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

The description is two sentences, with the main action front-loaded and a brief note on the DataStore requirement. Every word earns its place, making it 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?

For a simple read-only query tool with thorough parameter documentation and safety annotations, the description is fairly complete. It explains the resource source, the DataStore limitation, and indicates the output is rows. The lack of an output schema is not a gap since the description already states it returns rows.

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 the schema already explains each parameter fully. The description only mentions 'full-text q, limit, offset' without adding any new meaning beyond what the schema provides, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool pulls rows from a tabular CKAN DataStore resource by resource_id, specifying the data source (Slovenia Open Data) and the exact operation. It distinguishes itself from siblings like search_datasets or search_within by focusing on querying a specific resource's data.

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

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

The description provides clear context: you need a resource_id from a dataset's resources, and it notes the prerequisite that the DataStore must be enabled. It implies a workflow with search_datasets but does not explicitly name alternatives or when-not-to-use, 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 cover the read-only, idempotent, non-destructive safety profile. The description adds valuable behavioral context beyond annotations: scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual-mode behavior of omitting the key to list all keys. This enriches the agent's understanding but doesn't detail edge cases like missing keys.

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

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

The description is three sentences, front-loaded with the core action, followed by use case, scoping, and companion tools. Every sentence earns its place with no filler or repetition of structured data.

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

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

For a simple one-parameter tool with comprehensive annotations, the description covers purpose, usage context, scoping, and relationships to sibling tools. The absence of an output schema means return values aren't explicitly described, but that's a minor gap given the tool's simplicity and the implicit return of a saved value or key list.

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 reinforces the key parameter's optionality and effect: 'omit the key argument' to list all keys. It ties the parameter to the overall workflow, connecting it with 'remember' and 'forget', which adds value beyond the schema's simple type definition.

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 ('Retrieve', 'list') and resources ('value previously saved via remember', 'all saved keys'), clearly distinguishing it from siblings. It explicitly contrasts with 'remember' and 'forget' in the final sentence, eliminating ambiguity.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier' and provides concrete examples (target ticker, address, research notes). It also names the companion tools 'remember' and 'forget', implying when not to use this tool (for saving or deleting).

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?

Annotation contradiction: readOnlyHint=true conflicts with the description's statement that setting mark_read:true flags returned events as read, which is a state-changing side effect. While the description does disclose this behavior, the annotation actively misleads by indicating a purely read-only operation. This contradiction warrants a score of 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?

The description is extremely concise: four sentences, each earning its place. The first sentence states the primary purpose, followed by return format, filtering options, a side-effect note, and an alternative access method. No redundancy or padding.

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 does a good job by explicitly enumerating return fields (source, citation_uri, raw event payload) and covering key behaviors (filtering, mark_read, polling). The unread_only parameter is only covered by the schema, but the description remains sufficiently complete for a read-oriented 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?

All 5 parameters are fully described in the input schema (100% coverage), so the baseline is 3. The description adds a small amount of extra context, such as mark_read affecting subsequent calls, but this is supplemental rather than essential. The schema already provides clear parameter meaning.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull fired events), and the mention of filtering by type and mark_read adds scope. This effectively distinguishes it from sibling tools like list_subscriptions, which list subscriptions themselves.

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

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

The description provides clear usage context: polls work fine, and it points to an alternative HTTP endpoint for scripts/dashboards. However, it doesn't explicitly name sibling tools to exclude or state when not to use this tool. The main usage scenario (reading recent alerts) is well implied, but formal exclusions are absent.

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 traits beyond the annotations: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO, and the PatentsView API sunset May 2025 with soft-fail behavior. It also describes the return structure (changes[] grouped by source, total_changes count, and citation URIs). This adds significant context the annotations alone do not 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 dense but every sentence earns its place: examples, parameter formats, source behavior, return shape, and sibling distinction. It is well-structured and front-loads the most helpful usage examples.

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 explicitly describes the return format and includes essential behavioral details about the multiple data sources and fallbacks. It covers the `since` parameter and provides a clear differentiation from a sibling tool, making it complete 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 coverage is 100%, and both the schema and description document `since` accepting ISO date or relative shorthand. The description adds example queries but does not substantially enhance parameter meaning beyond the schema; it reinforces but does not extend the existing parameter descriptions.

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

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

The description states it is a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and provides numerous natural language examples. This clearly identifies the verb, resource, and scope, and distinguishes it from the sibling entity_profile.

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

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

Explicitly instructs when to use an alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' Also explains data source fallbacks (GDELT preferred, GNews when rate-limited or 5xx), which helps users decide when this tool is appropriate.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context: storage as key-value scoped by identifier, session persistence durations, and the pairing with recall/forget. It does not conflict with annotations, and the extra details about persistence and session scoping enhance transparency beyond the structured 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?

The description is concise and well-structured: it opens with the primary purpose, then gives usage criteria, storage details, and pairing hints. Each sentence adds value without redundancy, fitting in four impactful sentences.

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 2-parameter tool with no output schema, the description is complete. It covers what the tool does, when to use it, storage behavior (persistence, scoping), and related tools. No return value explanation is needed, and the annotations fill in safety and idempotency details.

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

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

Schema coverage is 100% with clear descriptions for 'key' and 'value', so the schema carries the main parameter meaning. The description adds context about key-value pair usage and examples, but this is marginal since the schema already explains the semantics well. 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 the tool saves data for later reuse, using the specific verb 'Save' and resource 'data' as key-value pairs. It distinguishes itself from siblings by explicitly pairing with 'recall' and 'forget' for retrieval and deletion, making its unique role clear.

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

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

It explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples (ticker, address, preference, research subject). It also clarifies persistence differences between authenticated and anonymous sessions. However, it does not explicitly state when not to use, though mentioning alternative tools (recall, forget) partially compensates.

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 well beyond the readOnlyHint/idempotentHint annotations. It discloses that each call 'cascades through several lookup endpoints internally,' returns specific fields including citation URIs, and auto-disambiguates inputs. These are valuable behavioral details that a user/agent would not otherwise know.

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

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

The description is somewhat lengthy but front-loaded with user intents and uses clear sectioning for supported types. Every sentence adds value (outputs, citations, usage guidance), though it could be trimmed slightly without loss.

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

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

Given there is no output schema, the description sufficiently enumerates return fields for both entity types, explains input flexibility, and notes internal cascading behavior. It covers ambiguity handling ('auto-disambiguated') and provides enough context for an agent to use the tool correctly in a variety of 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 already provides detailed parameter descriptions (enum for type, value format for each type). The description repeats this information with examples but adds no new parameter semantics beyond what the schema contains, so it does not elevate 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 clearly states 'resolve a user-spoken NAME to the canonical/official identifier' and enumerates supported entity types (company, drug) with their output fields. It distinguishes itself from sibling tools like entity_profile by focusing on name-to-ID conversion and explicit 'Use FIRST' guidance.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' Example user phrasings ('What's the ticker for...' etc.) make the trigger conditions concrete. This effectively communicates when to use this tool vs 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, idempotent, and non-destructive. Description adds valuable behavioral detail: it probes multiple entities, ranks by score, surfaces most/least recognized, and returns score/confidence/signal density. No contradictions.

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

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

Two sentences plus an example query and output summary. Front-loaded with the core purpose, though the parenthetical example could be trimmed. Efficient 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?

Given no output schema, the description explains return values (ranked list with score, confidence, signal density). Covers use case, mechanism, and output in enough detail for straightforward invocation. Slightly more context on models or output shape would push it higher, but it's 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 description coverage is 100%, so baseline is 3. The description adds little beyond the schema—it mentions 'your brand + N competitors' which is already in the schema's entity description. It doesn't significantly enhance 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?

Clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Provides explicit use case ('competitive AI-marketing audits') and an example query. Mentions the underlying ai_visibility_check mechanism, implying when to use this tool vs. that one, though it doesn't explicitly state alternatives or 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?

While annotations already declare readOnly, idempotent, and non-destructive, the description adds significant behavioral context beyond those: it warns about bundlephobia's first-measurement latency (5-30s), explains partial failures degrade gracefully with sources_failed listing, and clarifies that NPM-only is a version constraint. This substantially helps an agent set expectations.

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 densely packed and well-structured: it starts with the core purpose ('should I add this npm package'), then use cases, return values, ecosystem caveats, and failure behavior. Every sentence provides essential information for a composite tool with no output schema, so nothing is wasted.

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 absence of an output schema, the description thoroughly explains return values (summary block fields, per-advisory detail, links, recent alternatives), covers the NPM-only limitation, and details latency and partial-failure behavior. It is fully self-contained 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 description coverage is 100% for both parameters (package and version), including notes on scoped packages and defaulting to latest. The description largely restates what the schema already provides, adding no new parameter-level semantics beyond the already documented behavior. 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 defines the tool as a composite check for deciding whether to add an npm package, explicitly listing the data sources (deps.dev and bundlephobia) and the types of checks performed (license, advisories, bundle size, etc.). It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing specifically on npm package dependencies.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly states the ecosystem limitation (NPM only in v1) and directs users of other ecosystems to a direct deps.dev:version alternative, giving both when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds value by specifying the return structure (id/name, title, organization, resources) and the practical link to query_resource, which is useful beyond the annotations. 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 concise, consisting of two sentences that start with the core purpose and then list return items. No redundant or vague wording, every sentence contributes useful information.

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

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

For a search tool with three optional parameters and no output schema, the description provides sufficient context: the data source, intended use, return fields, and a link to a related tool. Minor aspects like pagination behavior are already covered by the schema. It is nearly complete for the tool's complexity.

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

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

Schema description coverage is 100%, with clear descriptions for all three parameters (limit, query, offset). The description does not add significant parameter details, but the baseline of 3 is appropriate since the schema fully documents the parameters.

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

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

The description clearly states the tool's function: 'Search Slovenia Open Data for datasets by keyword.' It specifies the resource (Slovenia Open Data) and the action (search), and differentiates from sibling tools by noting it returns datasets and their resources, with resource IDs intended for query_resource.

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

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

The description implies when to use this tool: to find datasets by keyword. It also provides a pointer to a sibling tool ('query_resource') by noting resources have a resource_id for that purpose, which gives some guidance on next steps. However, it does not explicitly state when not to use this tool or describe alternative tools for different scenarios.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavioral details: truncation at 200K chars with a flag, use of BGE-base-en embeddings, 500-char overlapping windows, and the return of character offsets and similarity scores. This significantly exceeds 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 four sentences, each adding distinct value: purpose, use case, pairing guidance, and technical implementation details. It is front-loaded with the core purpose and contains no redundant or filler content.

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

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

With no output schema, the description explains the return format (top-N passages with character offsets and similarity scores) and covers a key edge case (truncation for inputs over 200K chars). Combined with the strong annotations and schema, it provides complete context for an agent to use the tool correctly.

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

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

The input schema already provides detailed, meaningful descriptions for all three parameters (100% coverage), including the 200K char cap and query examples. The description adds no new parameter-specific information beyond what the schema states, so it stays at the baseline 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 clearly states the tool performs semantic search inside a previously fetched record, with a specific verb ('search') and resource ('a fetched record'). It distinguishes from siblings by emphasizing 'INSIDE a fetched record' and explicitly pairs with ask_pipeworx_grounded, clarifying its unique role.

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 when the record is too big to cram into the prompt' and explains the benefit of saving context. It also provides an explicit alternative pairing with ask_pipeworx_grounded, giving clear guidance on when to use this tool vs. 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?

It discloses return semantics (subscription id, webhook secret returned once), auth requirements, delivery behaviors (feed always on, email/SMS per event), verification prerequisites, the 10/day SMS cap, and auto-disable after 10 consecutive webhook failures. This goes well beyond the annotations and gives an agent a clear operational model of the tool.

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 densely packed, and every sentence conveys a necessary constraint or example. It front-loads the core purpose, then systematically covers type-specific params and delivery channels. No filler or repeated schema content is present.

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 three nested parameters, no output schema, and a rich set of subscription types, the description covers all necessary context: return values, supported types, examples, delivery modes, auth requirements, and failure behavior. It is complete enough for an agent to invoke the tool correctly without external documentation.

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

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

Even though schema coverage is 100%, the description enriches each parameter with concrete examples: 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}', 'polymarket_edge: {topic:"fed", min_spread_bps?:500}', and webhook details (HMAC signing, X-Pipeworx-Signature). It adds practical meaning beyond the schema field names.

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

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

The description clearly identifies the action ('Create a proactive monitoring subscription to a live-data event stream') and states the return value ('Returns the new subscription id'). It distinguishes this tool from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and by referencing the always-on feed and delivery channels.

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-not conditions: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)', 'phone must be verified at /account first', and a '10/day cap'. It also explains how to consume alerts ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'), giving clear context for when to subscribe and how to retrieve results.

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

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

Annotations already declare readOnly, idempotent, and openWorld, and the description adds substantial behavioral detail beyond that: it returns example questions with tool call shapes drawn from the live catalog, supports optional topic filtering, and serves as an onboarding entry. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with example queries, but it is slightly verbose with the enumerated question list. Every sentence adds value, yet it could be tightened without losing meaning, earning a 4.

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 a single optional parameter, no output schema, and rich annotations, the description fully covers usage, output content, and context. It explains what the tool returns, how to narrow results, and when to use it, making it complete for an agent to invoke correctly.

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

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

The input schema coverage is 100%, providing a full description of the `topic` parameter including valid values and the effect of omitting it. The description repeats this guidance ('pass `topic` to focus') without adding new meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns example questions categorized by domain, each with the exact tool and argument shape. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes itself from sibling tools by positioning it as the 'FIRST' step and linking to meta-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?

Explicit when-to-use guidance is present: '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 the optional `topic` parameter and the behavior of omitting it, giving clear context on how to invoke.

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 beyond annotations by disclosing that ownership is enforced, the row is deactivated rather than deleted, and historical events stay available via recent_alerts. This adds meaningful behavioral context that annotations alone do not convey.

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

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

The description is two sentences, front-loaded with the primary action and followed by essential constraints and consequences. Every sentence contributes valuable information without redundancy.

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

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

For a tool with a single parameter, clear schema, and relevant annotations, the description covers the essential behavioral aspects: cancellation, ownership, deactivation vs. deletion, and historical availability. It is complete for effective use.

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

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

The input schema already provides a clear description for the id parameter (uuid returned by subscribe), giving 100% coverage. The description does not add extra parameter semantics beyond the action itself, so it meets the baseline but offers no additional value.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action and adding ownership constraints.

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 provides clear context for when to use the tool (to cancel a subscription) and includes ownership enforcement and the deactivation behavior, which implies use cases. However, it does not explicitly name alternatives or exclusions, though mentioning recent_alerts hints at where historical events remain accessible.

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, covering the safety profile. The description adds valuable behavioral context: routing (SEC EDGAR/XBRL for company-financial claims vs. grounded pipeline for other claims), return contents (verdict types, actual value with citation, reasoning), and the fact it collapses multiple steps into one call. This goes beyond annotations without contradicting them.

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

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

The description is long but information-dense. It front-loads with user-intent examples and then packs routing, output, and efficiency details into a structured single paragraph. Every clause earns its place, though it could be more scannable with bullets or subheadings.

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 explicitly lists the return components (verdict, actual value with citation, reasoning). It covers both main use cases (financial vs. other claims), explains the fallback behavior, and notes the tool's efficiency. It is complete for a tool of this complexity 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 description coverage is 100% (2/2 params described), so the baseline is 3. The description does not add much beyond the schema; it mentions percent-delta math and tolerance overriding, but those are already explained in the schema's tolerance_pct description. The claim examples in the schema are even more illustrative.

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 natural-language triggers ("Is it true that…", "fact check") and explicitly states "natural-language claim verification against authoritative sources." It clearly distinguishes itself from sibling tools like ask_pipeworx by focusing on fact-checking with a verdict output, not general Q&A.

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

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

The description says "Use whenever the agent needs to check whether something a user said is factually correct," providing an explicit when-to-use. It does not name alternative tools or state when-not-to-use, but it implicitly differentiates by describing the two verification pipelines and noting it replaces 4–6 sequential calls, offering a performance rationale.

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