Kolada Se

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

Annotations indicate safe read operation (readOnlyHint, idempotentHint). Description adds key behavioral context: default model is free, Anthropic requires own key and direct payment, and return structure. 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?

5 sentences, each adding distinct value: purpose, default behavior, key requirement, return format, use cases. No filler or redundancy.

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

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

Despite no output schema, description fully explains return format. Covers all parameters, usage scenarios, and expected output. No gaps given tool complexity.

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

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

Schema has 100% description coverage, but description adds value beyond: explains default model, cost implications for _apiKey, and return format (per-model score, confidence, signals, raw_response). This compensates for no output schema.

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

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

The description uses specific verb 'probe' and resource 'LLMs' for an entity, with quantifiable output (score 0-100). It clearly distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on multi-model visibility scoring.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Explains when to use free Workers AI vs BYO Anthropic key. Lacks explicit 'when not to use', but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful behavioral context beyond that: this is a router that selects among many tools, fills arguments, returns citations, and is a single fast call. This helps the agent set expectations about delegation and response format.

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

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

The description is long but every sentence earns its place: domain coverage, trigger phrases, examples, routing guidance, and alternatives. It is front-loaded with the most important directive and uses scannable examples. Slightly verbose in the domain list, but not redundant.

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 low complexity (one real parameter) and no output schema, the description gives sufficient context: when to use, what it returns, when to escalate, and that it works on every tier. It does not explain how to parse pipeworx:// URIs, but that is a minor gap for selecting and invoking the tool.

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

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

The schema covers all 6 parameters with 100% description coverage, and all are aliases of 'question'. The description does not add new parameter-specific meaning beyond what the input schema already provides, so the baseline of 3 applies.

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

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

The description names a specific verb (routes, returns), a resource (questions to 5,743 tools across 1500 sources), and deliverable (structured answer with pipeworx:// citation URIs). It clearly distinguishes from siblings by naming the alternatives for when to step up, so an agent can tell it apart without opening schemas.

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 'PREFER OVER WEB SEARCH', lists concrete trigger phrases ('what is', 'look up', 'find', 'get the latest'), and gives six examples. It also states when NOT to use it and routes to ask_pipeworx_grounded or deep_research with conditions, making usage guidance unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful non-obvious context: candidate routing is enabled live only when under test, no candidate is currently active so it matches ask_pipeworx exactly, and it falls back to nothing because it is a full working router.

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 efficiently structured and front-loaded with the core identity ('Beta version of ask_pipeworx'). Every sentence adds value: current state, active-candidate status, usage instruction, and fallback clarification, with no wasted words.

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

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

For a router tool with a full input schema and safety annotations, the description covers everything needed: what it is, how it relates to ask_pipeworx, when to use it, its current behavior, and that the response shape matches the stable version. No essential context 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 description coverage is 100%, and the schema already documents the required question parameter plus its five aliases. The description only adds 'same arguments' as a reference to ask_pipeworx, providing no additional parameter-level meaning beyond the schema.

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

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

The description clearly defines the tool as a beta version of ask_pipeworx: an identical universal router with the same 5,743 tools, arguments, and response shape. It distinguishes itself from the stable sibling ask_pipeworx by being the experimental edge where candidate routing improvements are tested, so an agent can tell them apart.

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 it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide what merges. This gives a clear condition for selecting this tool over its stable sibling.

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

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

Even though annotations already indicate readOnly/idempotent/non-destructive behavior, the description adds critical behavioral detail: it performs multi-step tool routing, returns either a grounded answer with evidence/confidence/fetched_at or an explicit refusal with a specific refusal_reason, and costs an extra LLM call versus ask_pipeworx. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return shape, refusal semantics, use cases, and cost tradeoff. The most important distinction is front-loaded.

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

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

For a complex tool with no output schema, the description fully compensates by enumerating the success response fields and the complete refusal_reason enum. It also states the cost, relationship to the sibling, and suitability criteria, leaving no material ambiguity for invocation.

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

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

Schema coverage is 100% and all six parameters are clearly documented as aliases for a single natural-language question. The description does not add deeper parameter semantics, but it doesn't need to: there is only one semantic input and the schema already explains it well.

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 names a specific mode ('Hallucination-resistant answer mode for high-stakes reads'), a distinct behavior (extracts only from tool result), and explicitly frames how it differs from ask_pipeworx. This makes it immediately distinguishable from sibling tools like ask_pipeworx and ask_pipeworx_beta.

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 gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on'), cites high-stakes examples, and tells the agent when NOT to use it ('prefer ask_pipeworx for casual lookups') and why (extra LLM call cost). This is exemplary routing 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 discloses extensive behavioral traits beyond annotations, including market resolution, classification, fan-out logic, response shapes, error conditions (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), resolution-rule risk, and edge cases. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. Every sentence provides essential detail, and the length is justified by the complexity of the tool. No redundancy or unnecessary 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?

Without an output schema, the description fully explains all return values, error modes, edge cases (e.g., cancellation rules, wide spreads, closed markets), and resolver contract. It covers all necessary details for correct invocation and interpretation, making it highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant context by explaining the fan-out behavior, response shapes, and providing examples for each parameter. This extra detail helps the agent understand how parameters affect the tool's behavior beyond the schema descriptions.

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

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

The description states a specific verb ('Research') and resource ('Polymarket bet') and clearly defines inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). Although sibling tools are not explicitly contrasted, the usage examples and scope make the purpose distinct and unambiguous.

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

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

The description explicitly lists use cases ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'), providing clear context for when to invoke. However, it does not mention when to use alternatives or when not to use this tool, which would improve the score.

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

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

The description adds significant behavioral context beyond annotations: it discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, sorting by primary metric, and citation URIs. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is a single paragraph that efficiently packs all necessary information: trigger phrases, entity types, data sources, sorting, and value proposition. No redundant 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?

Given the tool's complexity (two entity types, multiple data sources, no output schema), the description covers input semantics, data sources, sorting, and the benefit of replacing multiple lookups. It leaves little ambiguity 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?

Schema coverage is 100% with parameter descriptions, but the description enriches semantics by specifying exact data pulled for each type (e.g., revenue, net income for companies; adverse-event counts for drugs) and providing example inputs (tickers, drug 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 states that the tool performs side-by-side comparison of 2–5 companies or drugs in a single parallel call. It lists trigger phrases like 'Compare X and Y' and explicitly distinguishes from sequential single-entity lookups, making its purpose unmistakable.

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

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

The description explicitly recommends preferring this tool over sequential lookups when comparing entities. It explains behavior for each entity type (company vs drug). While it doesn't explicitly state when not to use, the context is clear enough for an agent to decide.

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

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

Descriptions adds substantial behavior beyond annotations: account/paid-tier requirements, parallel decomposition across 5,743 tools, gaps[] behavior (never invented), contradictions[], semantic excerpting, citation_uri resolvability, and latency expectations. This is far more than the read-only/idempotent hints convey and helps set accurate agent 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 richly informative, front-loaded with the critical auth constraint and the primary sibling distinction. Some repetition occurs (gap recovery and contradictions are mentioned multiple times), but the density is justified for a complex tool with 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?

Covers return packet structure, timing, auth, alternatives, depth semantics, citation behavior, and failure modes. With no output schema, the description fully carries the responsibility for explaining what the agent will get back, and it does so completely.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the question parameter is fine with broad/multi-part queries, by giving default depth ('standard'), and by spelling out the paid plan implication for 'thorough' — beyond the schema's enum 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?

States a specific verb+resource ('grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources') and explicitly differentiates from ask_pipeworx, so an agent can distinguish them. Includes concrete examples of target use cases and what the tool is not (open-web search).

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 and when-not-to-use guidance: best for broad/multi-part structured questions, single lookup or breaking news should go to ask_pipeworx, and signed-out users should use ask_pipeworx. Also gives depth-selection guidance (standard default, thorough paid, quick single-hop).

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: returns top-N tools with full schemas and curated examples, ready to call. No contradictions.

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

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

The description is appropriately sized, front-loaded with purpose, then examples, then usage guidance. Every sentence adds value with no wasted words.

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

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

Given the tool's complexity (6 params but many aliases, no output schema), the description sufficiently explains what the tool does and what it returns. It mentions the return format (top-N tools with schemas and examples), making it complete enough for an agent to use.

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

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

Schema coverage is 100% and parameter descriptions are detailed. The description adds context that query accepts aliases and examples of natural language usage, but much of this is already in the schema. Baseline is 3.

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

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

The description clearly states a specific verb ('Find') and resource ('tools by describing the data or task'), and lists multiple example domains (SEC filings, FDA drugs, etc.). It distinguishes itself from sibling tools by being a discovery/search tool for tools themselves, not for 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 explicitly says 'Call this FIRST when you have many tools available and want to see the option set'. This provides clear context for when to use. It does not explicitly state when not to use or name alternatives, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds a wealth of behavioral context beyond annotations: the fan-out across multiple sources, the soft-fail behavior for patents (USPTO API sunset), the specific return structure (cik, resolved_from/resolved_to, recent_filings URIs), the fact that empty sections are expected not failures, and the naming resolution behavior. It also discloses a limitation (private companies). The only minor gap is not explicitly stating response format/pagination, but for a data-fetch tool this is well-covered. Would be a 5 except it stumbles slightly on clearly communicating the 'news via GDELT→GNews fallback' with a single arrow, which is somewhat terse.

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 information-packed, with a clear structure: triggers first, then the approach directive, then a bulleted enumeration of sources and return fields, then parameter guidance. It is front-loaded with the most critical usage direction ('ALWAYS PREFER'). However, it is quite long, and some sentences run on (the return-list sentence is a wall of text). It earns its length because every clause adds useful information, but it could be slightly more scannable with line breaks or headers. It's not bloated with fluff, so a 4 rather than 3, but not a 5 due to the run-on structure.

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 high complexity (multiple data sources, multiple return sections, edge cases, fallbacks), the description is remarkably complete. It covers: input formats, name resolution, private-company behavior, expected empty sections, source failure semantics, and explicit examples of returns like resolved_from/to. The output schema is absent, so the description must convey the return structure, which it does thoroughly (cik, company_name, recent_filings URIs, fundamentals with sort order, etc.). No critical information that an agent needs to call and interpret correctly is missing. The description even explains why a section might be empty (e.g., small-molecule-only companies showing no fda_products). This is a model of completeness for a complex data-fetch 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%: both `type` and `value` are fully described in the schema itself, including the note about interchangeability. The description reinforces this by providing concrete examples ('AAPL', '0000320193', 'Moderna') and clarifying that names resolve via SEC EDGAR. It adds the exact accepted shapes and behavior when a private company is given. This exceeds the baseline 3 because the description provides examples and edge-case behavior not in the schema, but since the schema already covers the basic semantics, a 4 is appropriate rather than 5.

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 is exceptionally specific: it lists multiple natural-language triggers, names the primary resource (full cross-source profile of a US public company), and distinguishes itself from alternatives by explicitly stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It clearly differentiates from siblings like deep_research, compare_entities, and resolve_entity by defining its scope. The verb 'profile' plus the enumerated data sources makes purpose unambiguous.

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

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

The description provides explicit when-to-use guidance with imperative language ('ALWAYS PREFER') and specific examples of triggering queries. It names the alternative approach (chaining single-pack lookups) and the condition for preferring this tool. It also covers edge cases: private companies return resolved:false with notes, and expected empty sections are explained. The note about 'sources_failed' being real no-data vs bug provides critical interpretational guidance.

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

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

Annotations already indicate destructive behavior. The description adds useful context about why to delete (stale context, done tasks, sensitive data) beyond what annotations provide, but no contradictions.

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

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

Three concise sentences front-load the purpose, then usage guidelines, then related tools. No wasted words.

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

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

For a simple delete operation with one required parameter and no output schema, the description is complete: it explains what, when, and how it relates to other tools.

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

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

Schema coverage is 100% with the 'key' parameter described as 'Memory key to delete'. The description adds 'by key' but no additional detail beyond the schema, meeting 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 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use (context is stale, task done, clear sensitive data) and pairs with related tools (remember, recall), providing clear guidance.

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

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

Annotations already indicate read-only, non-destructive, idempotent. Description adds behavioral details: fetches the page, extracts title/description/key links, and outputs a single text blob. No contradictions.

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

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

Two sentences: first states the core purpose, second lists use cases. Front-loaded and concise with no fluff.

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

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

Covers purpose, usage, output format, and use cases. No output schema needed; description mentions output type. Lacks error handling or edge cases but sufficient for a simple tool with rich annotations.

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

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

Schema coverage is 100% and descriptions are already detailed. The description does not add extra meaning for parameters beyond what the schema provides.

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

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

Explicitly states it generates an llms.txt file for AI crawlers, with specific actions (fetch, extract, emit). Clearly distinct from siblings like scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

Lists three concrete use cases (client indexing, personal project, competitor audit). No explicit when-not-to-use or alternative tool references, but context is clear.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds useful context about the return format (gender breakdown, non-gendered KPIs) and no contradictions. It adds 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 two sentences but contains redundancy (gender breakdown repeated). It is front-loaded with the main purpose, but could be more concise.

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

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

No output schema exists, so the description partly explains the return structure (gender breakdown). However, it lacks details on error cases, response format, or potential issues. The fragment 'T.municipalityId from list_municipalities' is confusing.

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

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

Schema coverage is 100% with descriptions for all parameters. The description repeats the role of parameters (e.g., 'municipalityId from list_municipalities') but adds no new syntactic or semantic details beyond what's in 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 fetches numeric KPI values for a specific indicator, municipality, and year. It uses a specific verb and resource, but does not explicitly differentiate from siblings like compare_entities or search_kpi.

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

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

The description implies that the tool is used when you have a specific kpiId, municipalityId, and year, and hints at using sibling tools (list_municipalities, search_kpi) to get IDs. However, it lacks explicit guidance on when not to use it or 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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the tool's safety profile is clear. The description adds behavioral context: it returns specific fields (id, title, type) and explains the type codes (K vs L with counts). This supplements the annotations well.

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: first states core function, second explains return types, third gives usage tip. No extraneous words, well-structured, and front-loaded with key information.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what an agent needs: purpose, input, output, usage pattern, and relationship to sibling tool get_data. No gaps.

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

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

Schema description coverage is 100%, so the schema already documents the parameter. The description adds meaning by clarifying that 'title' is a substring, and that omitting it lists all. This goes beyond the schema's basic description.

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

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

The description clearly states the tool finds municipality/region ids by name substring, specifies the resource (Sweden municipalities/regions), and explains the return values (id, title, type). It effectively differentiates its purpose from siblings by linking to get_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 explicitly tells when to use the tool (to find ids by name substring) and how to use the returned id with get_data. It also provides a key usage tip: omit title to list all. This distinguishes it from alternatives like get_data.

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 establish read-only, idempotent behavior. The description adds context about the data source (RKA/Kolada) and return fields (id, title, municipality), plus the hint that OU ids enable further analysis. This complements the annotations without contradiction.

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

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

The description is compact, front-loads the core action ('list the organizational units'), and packs domain context, return fields, and a usage hint into two sentences with no fluff.

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

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

For a simple list tool with optional filters and no output schema, the description adequately covers what is returned (id, title, municipality), how to filter, and the domain background. No critical information 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?

The input schema fully documents both parameters with examples and descriptions, and schema coverage is 100%. The description only restates the filter capability without adding new semantic detail, 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 the tool lists organizational units tracked by Kolada within Swedish municipalities/regions, with specific examples (schools, preschools, eldercare). It distinguishes itself from siblings like list_municipalities by focusing on units rather than municipalities.

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

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

The description gives clear context: use when you need org units and their ids for drilldowns. It does not explicitly name alternatives or exclusions, but the scope is obvious and the mention of OU ids for unit-level data drilldowns implies a specific use case.

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 adds the return value format, which is beneficial. No contradiction.

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

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

Two sentences covering purpose, output, and usage guidance. No filler, efficiently 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?

Simple tool with one param. Description covers purpose, output fields, and usage context. Lacks mention of potential pagination or error states, but acceptable for a straightforward 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 documents the only parameter (include_inactive) completely. Description does not add new parameter info beyond implying active-only default, but this is aligned. Baseline 3 due to full 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 it lists the caller's active subscriptions and specifies the return fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from sibling tools like subscribe and unsubscribe by using 'list' as the verb.

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

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

Explicitly advises when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies alternatives (subscribe/unsubscribe) for modification.

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

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

With all annotations set to false, the description carries the full burden of behavioral disclosure. It does so thoroughly: filing without an account returns a claim_token, the token can be passed back later to check status, there's a daily rate limit of 5 per identifier, and the action doesn't count against tool-call quota. 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 every sentence contributes: purpose, usage, exclusions, style guidance, token flow, operational details. It is front-loaded with purpose and usage. While it could be tightened slightly, the density of useful information justifies the length.

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

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

The tool has moderate complexity (4 params, nested object, no output schema), and the description covers all necessary context: when to use, what to include, how to follow up, rate limits, and impact. The absence of an output schema is mitigated by the explicit claim_token explanation. Highly complete.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds meaningful extra context for claim_token (how to pass it back later and what it returns), which goes beyond the schema's description. However, since the schema already covers most semantics, the incremental value is modest but real.

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+target: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the tool's function and scope. It also distinguishes itself from sibling tools like ask_pipeworx by focusing on reporting issues about Pipeworx tools 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 explicitly enumerates when to use the tool (bug, feature/data_gap, praise) and provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It even clarifies ambiguity around tool ownership. This is exemplary usage guidance.

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

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

Description discloses caching behavior, data source (CF analytics-engine), no PII, and self-aggregating nature. Annotations already mark readOnly, idempotent, and nondestructive; the description adds valuable operational context without contradiction.

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

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

Extremely concise: three sentences plus a bullet list. Front-loaded with output summary, no redundant phrasing. Every sentence earns its place.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description fully covers purpose, use cases, behavior, and parameter. No gaps remain.

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

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

Schema coverage is 100% for the single parameter, so baseline is 3. Description adds value by explaining the meaning of different window choices ('hot right now' vs 'steady-state demand'), exceeding schema documentation.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window'. It differentiates from siblings like discover_tools by focusing on trending/aggregate data rather than search or entity discovery.

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

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

Explicitly lists three specific use cases, providing actionable context for when to use. Could be stronger by stating when not to use or naming alternatives, but the guidance is clear and practical.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds rich behavioral context: default trending scan behavior, partition check mechanics, Jaccard similarity filter, placeholder filter, fill check against live depth. No contradiction with annotations.

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

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

The description is comprehensive but slightly verbose. It is front-loaded with the main purpose and modes, then details each aspect. Every sentence adds value, but could be more tightly edited without losing information.

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

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

Given no output schema, the description adequately describes the response structure (opportunities, partition_check, fill_check) and covers key details like default behavior, filter logic, and trade signals. It provides sufficient context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds significant value beyond schema: explains the purpose of each parameter, provides usage examples (event slugs, topic questions), and clarifies the difference between single-event and cross-event modes.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two distinct modes (event and topic) and differentiates from sibling tools like polymarket_edges by specifying its unique arbitrage logic.

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: recommends event mode for a specific market, topic mode for cross-event scanning. Also advises when not to trade (realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing, providing clear exclusion criteria.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes far beyond by detailing internal models, calculations, output fields (edge_pp_net, kelly_fraction, liquidity, etc.), and caching behavior. 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 long but packed with valuable information. It is structured with segment labels and bullet points within a paragraph. While dense, it avoids redundancy and every sentence adds value. Could benefit from more explicit section breaks for readability.

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

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

For a complex tool with 9 parameters, three segments, and no output schema, the description covers all aspects: segments, calculations, output fields, parameter knobs, edge cases (Fed bets), diagnostics, and caching. It provides a fully self-contained explanation of what the tool returns and how to use it.

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

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

Schema coverage is 100%, baseline 3. The description adds substantial context for each parameter: explains min_kelly as half-Kelly fraction, slippage_pp in context of Polymarket fees, max_spread_pp as tradeable-edge filter, etc. It provides practical advice like 'drop to 0 if you have a smarter fill model'.

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

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

The description clearly states the tool scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on data disagreement and providing a use case.

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

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

The description provides detailed guidance on when to use each segment (model_driven, structural_arbitrage, concentrated_longshot) and explains tradeable-edge knobs. It implicitly differentiates from siblings by specifying the unique Pipeworx data disagreement aspect. However, it lacks explicit 'use this instead of X when' statements.

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 extensive behavioral details beyond the annotations: response structure (tracked, expired, snapshot_dates), computation of trend and decay, limitations like 60-day snapshot TTL and daily closes vs intraday. 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, front-loading the purpose, then detailing output and limitations. It is somewhat verbose but every part serves a purpose. Slightly longer than necessary but still effective.

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

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

Given no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and key fields like first_seen, trend, decay_pp_per_day. It also covers limitations and snapshot availability, leaving no obvious gaps.

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

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

Schema coverage is 100%, but the description adds meaning by explaining defaults (14 days, '1wk' window) and the clamp for days. It also clarifies the 'window' parameter as 'snapshot family'. This adds value beyond the schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry built from daily polymarket_edges snapshots', with a specific question it answers ('how long has this edge existed and is it shrinking?'). It distinguishes from siblings by contrasting fresh vs. old edges.

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

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

The description gives clear context for when to use the tool (to assess edge age and decay) and explains the significance of an old wide edge. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient for an agent to decide.

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

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

Provides extensive behavioral details: walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, verdict, forced_directional_risk, etc. Annotations (readOnly, openWorld, idempotent, non-destructive) align with description.

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

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

Well-organized with bold headings and structured lists, but slightly verbose. Every sentence adds value, yet length could be trimmed for faster parsing.

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

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

No output schema, but description thoroughly lists all return fields for both modes, covers edge cases (partial fills, thin legs), and explains verdicts. Complete enough for an agent to understand tool behavior.

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

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

Although schema description coverage is 100%, the description adds rich context for each parameter: explains side's auto behavior in basket, size_usd interpretation difference between modes, clamp range, and relationship to modes.

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 is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises using this tool before acting on polymarket_arbitrage signals or trades above ~$500, explaining why theoretical overround on thin books is not capturable and partial fills create 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses extensive behavioral detail: compatibility warning codes, temporal alignment semantics, fee treatment, unclassified leg exclusion, paired-leg flagging, and skipped cross-type/subtype counters. It thoroughly explains edge cases like temporal_alignment_unknown being distinct from confirmed alignment, adding far more transparency than the annotations alone.

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 it is densely packed with necessary information and clearly structured with labeled sections: TWO MODES, RESPONSE, SAFETY FIELDS, codes enumeration, and fee disclosure. Every sentence contributes to correct usage or interpretation of results, and the most important caveats are front-loaded near the top.

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 return values, and it does so thoroughly: response shape, top_spreads_pp, compatibility codes, temporal_alignment, fees_note, skipped counters, and low-confidence pairs. For a tool with this complexity and zero required parameters, an agent has enough context to invoke it correctly and interpret ambiguous or risky 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?

The schema already describes all three parameters with examples and override semantics (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema by explaining that explicit ticker/slug parameters override the topic-mapped side, that both modes run an identical token-overlap matcher, and how the topic list behaves as pre-mapped shortcuts. This compensates well 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 clearly defines the resource: a cross-venue spread between Kalshi and Polymarket for the same resolving question, and explains the core idea of equivalent bet shapes. It does not explicitly differentiate this tool from siblings like polymarket_arbitrage or polymarket_edges, but the 'cross-venue' framing and detailed mode descriptions make the purpose unmistakable.

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

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

The description gives clear guidance on when to use each of the two modes: pre-mapped topic shortcuts versus explicit custom ticker/slug pairings, including that both modes run the same matcher. It does not explicitly name alternatives among sibling tools or state 'use X instead of Y', but it provides strong contextual usage guidance and warns that pre-mapped topics are not automatically tradeable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds scoping to identifier and the effect of omitting key (listing all). No contradiction. The description provides moderate extra context beyond annotations.

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

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

Two sentences, well-structured, no redundancy. Key action is front-loaded, and every sentence adds value. Excellent conciseness.

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

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

Given the tool's simplicity (one optional parameter, no output schema, annotations clear), the description fully covers its usage, scope, and relationship to sibling tools. No gaps.

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

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

Schema coverage is 100% with the 'key' parameter described. The description adds crucial usage detail: omitting key lists all keys. This gives the agent semantic understanding beyond the schema 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 clearly states it retrieves a value saved via remember or lists all keys, with a specific verb ('retrieve') and resource (memory). It distinguishes itself from siblings 'remember' and 'forget' by specifying the retrieval and listing behavior.

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

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

The description gives explicit examples of when to use (recalling stored context like ticker, address, notes) and mentions scoping and pairing with remember/forget. It lacks explicit 'when not to use' but provides sufficient context for usage decisions.

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 destructiveHint=false, but the description adds crucial context: the mark_read parameter flags events as read, affecting subsequent calls, and describes the return structure (source, citation_uri, payload). This explains state management 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?

Three sentences, front-loaded with purpose, dense with information. Every sentence provides value without unnecessary elaboration.

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 explains the return structure (source, citation_uri, payload) and covers all parameter use cases. It also mentions an alternative access method, making it fully adequate for a read-only polling 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?

With 100% schema coverage, the baseline is 3. The description adds value by explaining the effect of mark_read ('so the next call only shows newer ones') and clarifying that 'type' filters to one subscription type and 'since' uses ISO timestamp for fired_at.

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 verb 'Pull' and specifies the resource 'fired events from your subscription feed', clearly distinguishing it from sibling tools like 'recent_changes' or 'subscribe'. It also details key filters and the mark_read feature.

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

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

The description states 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards', providing an alternative for scripting use and implying the tool is for interactive polling. It does not explicitly state when not to use it, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations: fans out to multiple sources (SEC, GDELT/GNews, USPTO), includes fallback logic, and notes USPTO soft-fails. 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?

Description is a single paragraph with four sentences, front-loaded with example queries. It covers all key aspects without redundancy. Could be slightly tighter or use bullet points, but overall well-structured and concise.

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

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

For a tool with 3 params, no output schema, and moderate complexity, the description is fairly complete: covers return format (changes grouped by source, total_changes, citation URIs), sources, fallback, and failure mode (USPTO soft-fail). Missing error scenarios, but adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds usage examples for `since` (ISO date and relative shorthand) and clarifies `value` accepts ticker or zero-padded CIK. It recommends '30d' or '1m' for monitoring, going beyond schema descriptions.

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

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

The description clearly states the tool's purpose as a change feed for a company in the last N days/weeks/months, with specific example queries. It explicitly distinguishes from the sibling tool entity_profile, saying 'Use entity_profile instead when you want the static 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?

Provides explicit context on when to use (e.g., 'What's new with X') and when not to (static profile should use entity_profile). It details fallback behavior (GDELT to GNews) and recommends '30d' or '1m' for typical monitoring.

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

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

Beyond annotations (idempotentHint: true, destructiveHint: false), the description discloses scoping ('scoped by your identifier') and expiration ('Anonymous sessions retain memory for 24 hours'). This adds significant value beyond the structured fields.

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

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

The description is a single, well-structured paragraph. Every sentence adds new information, with no redundancy or wasted words.

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

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

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description covers storage mechanism, scoping, persistence duration, and companion tools. It is fully sufficient for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds practical examples ('subject_property', 'target_ticker') that enhance understanding, but the schema already does most of the work.

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: 'Save data the agent will need to reuse later.' It clearly distinguishes from siblings like recall and forget, which are listed in the 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 when you discover something worth carrying forward') and mentions companion tools (recall, forget). It does not include a 'when not to use' statement, but the context is clear.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing nuanced behavior: identifiers may be returned under an 'unresolved' list rather than omitted, ambiguous matches return 'figi_candidates', enrichment degrades gracefully if GLEIF/OpenFIGI are unavailable, and ISIN inputs are mapped to legal entities. This gives the agent accurate expectations for edge cases.

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

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

The description is a dense, long single paragraph, but it front-loads the key trigger and supported types, and nearly every sentence adds functional detail. It is not concise in length, yet it contains very little waste; a slight structural improvement would make it fully 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 compensates by detailing expected return content: CIK, ticker, LEI, FIGI, RxCUI, sources, unresolved identifiers, and candidate lists. It also covers failure modes and lookup behavior, so an agent has enough information 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?

Although schema coverage is 100%, the description adds substantial semantic value: it explains accepted input forms for company (ticker, CIK, ISIN, name), brand/generic for drug, and gives a precise caveat about passing only the issuer name for bonds. This clarifies the schema beyond its basic type/value 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 concrete user-phrase examples and states the operation explicitly: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It identifies the resource type (entities like company/drug) and the exact outcome (canonical identifiers), making the purpose unmistakable and differentiated from sibling tools such as entity_profile or compare_entities.

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

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

The description gives a strong, explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also clarifies input forms and the 'ENTITY NAME ONLY' rule for bonds. However, it does not name sibling tools or state when-not-to-use conditions, so the guidance is excellent on condition but lacks explicit alternative differentiation.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds transparency by explaining that it internally calls ai_visibility_check for each entity, and describes the output structure (ranked list with score, confidence, signal density). 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?

Two efficient sentences. Front-loaded with purpose and method. No redundancy or waste. Every sentence adds value.

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

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

Despite no output schema, the description fully explains the return format (ranked list with score, confidence, signal density). It also describes the internal probe mechanism. For a 4-parameter, moderate-complexity tool, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning: 'first entry treated as subject for narrative', array size limit 2-8, default model, and context disambiguation. This goes beyond the schema descriptions.

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

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

The description uses specific verb 'compare' and resource 'AI visibility', clearly differentiating from sibling tools like ai_visibility_check (single entity) and compare_entities (generic). It details the process: probes each entity, ranks by score, surfaces most/least recognized.

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

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

The description states it is 'useful for competitive AI-marketing audits' and provides a concrete example question. It implicitly suggests using ai_visibility_check for single-entity checks, but does not explicitly list exclusions or alternatives. The context from sibling tools helps, but the description could be more direct.

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 safety and idempotency. The description adds significant behavioral context: composite nature, external service fan-out, partial failure behavior, and slow first measurement. 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?

One dense paragraph front-loading purpose, then sources, usage, limitations, and output. Every sentence is informative with no fluff. Highly efficient.

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

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

Covers all essential context: composite nature, external sources, usage scope, timing, failure handling, and output format (summary block, advisories, versions). No gaps given the lack of output schema.

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

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

Schema covers both parameters (package, version) with descriptions (100% coverage). Description adds value: scoped package acceptance and version default behavior. Also details the output structure, compensating for lack of output schema.

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

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

The description clearly states this is a composite check for evaluating an npm package across deps.dev and bundlephobia, using specific verbs like 'scan' and 'check'. It distinguishes from siblings by focusing on package evaluation and gives example queries like 'is X safe / popular / small'.

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

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

Explicitly says when to use (agent asks about safety/popularity/cost) and when not to (non-npm ecosystems fall under deps.dev directly). Also warns about timing (5-30s for bundlephobia first measurement) and mentions graceful partial failures.

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

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

Description adds significant behavioral context beyond annotations: it specifies the search mechanism (substring in Swedish), the number of indicators, and the exact return fields (id, title, description, operating_area, is_divided_by_gender). 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?

Two sentences, front-loaded with the main action. No fluff, every sentence adds value. Efficient and clear.

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

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

Despite no output schema, the description explicitly lists return fields and explains how to use the result. Covers scope, data categories, and next steps. Sufficient for an agent to understand and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new parameter-level details beyond what the schema already provides (e.g., title is a Swedish substring, pagination params). Examples in schema help but description itself does not elaborate.

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 'Find Kolada KPI (indicator) ids by title substring (Swedish)' with a specific verb and resource. It distinguishes itself from sibling tools like 'get_data' by explaining the purpose and how the returned id is used.

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

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

Provides context on the scope (~5,000 indicators, categories) and explicitly instructs to use the returned id with 'get_data'. However, it lacks explicit 'when-not-to-use' or alternatives among siblings, though the sibling list is large and mostly unrelated.

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

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

Discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), and character cap (200K chars with truncation flag) – all beyond readOnly/openWorld/idempotent annotations. No contradiction.

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

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

Single paragraph, front-loaded with purpose and usage, then technical details. Dense but efficient – every sentence adds value. Could benefit from clearer structuration but remains effective.

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

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

No output schema, but description explains return format (top-N passages with offsets and scores). Covers cap, truncation behavior, and pairing guidance. Complete for a 3-param tool with comprehensive annotations.

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

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

Schema coverage is 100% so baseline is 3, but description adds examples for query ('supply-chain risk') and context for text and limit (e.g., 'top-N passages'). Adds moderate value beyond schema descriptions.

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

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

Clearly states 'Semantic search INSIDE a fetched record,' specifying verb, resource, and context. Distinguishes from siblings by noting it pairs with ask_pipeworx_grounded and is for in-document search.

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

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

Explicitly advises usage when record is too large for the prompt, saving context. Provides clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 are already present, and the description adds substantial context: subscription creation, requirement for OAuth, return of subscription ID, and detailed delivery channel behaviors (SMS cap, webhook signing, auto-disable). No contradictions with annotations.

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

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

The description is front-loaded with the purpose and requirements, then elaborates on types and delivery channels. It is slightly verbose but every sentence adds value given the complexity. Could be slightly more concise without losing information.

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

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

Given no output schema, the description mentions 'Returns the new subscription id' but does not detail the full response structure. However, it covers prerequisites, types, delivery, and constraint details. Slightly incomplete on return format but sufficient for an agent.

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

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

Schema coverage is 100%, and the description provides detailed examples for each type's params (e.g., sec_8k, polymarket_edge) and explains delivery channel validation and constraints, adding significant meaning beyond schema definitions.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. This specific verb+resource combination distinguishes it from sibling tools like list_subscriptions or unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account and notes that anonymous/BYO users cannot persist subscriptions. It also lists supported types and delivery channels, but does not directly contrast with sibling tools like list_subscriptions or recent_alerts, though context implies when to use.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description adds that the tool returns live category-bucketed example questions with exact tool/argument shapes. This provides useful behavioral context beyond what annotations indicate.

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

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

The description is front-loaded with user intents and well-structured, but slightly verbose. Every sentence contributes value, though minor trimming could improve conciseness.

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

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

Despite no output schema, the description fully explains what the tool returns (category-bucketed examples with tool calls) and how to use it for onboarding. Complete for its purpose.

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

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

Schema coverage is 100%, but the description enriches the topic parameter by listing focus areas and explaining the effect of omission (full spread). This adds value over the schema description.

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

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

The description clearly states the tool returns category-bucketed example questions for onboarding, distinguishing it from siblings like ask_pipeworx or discover_tools. It lists multiple user intents and specifies the output 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 explicitly advises using this tool FIRST when unsure about Pipeworx's capabilities, and explains when to omit or provide the topic argument. However, it does not explicitly compare with sibling tools or state when not to use.

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

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

Discloses key behavior beyond annotations: row is deactivated not deleted, historical events remain available. Annotations already indicate non-destructive and idempotent, but description adds context.

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

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

Three sentences with no wasted words. Purpose is upfront, followed by ownership constraint and deactivation behavior. Each 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 simple schema (1 param, no output schema) and clear annotations, the description fully covers what an agent needs: purpose, behavior, ownership, and side effects.

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

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

Schema covers the single parameter fully with description. Description adds no new semantic meaning beyond what schema provides, meeting baseline.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource. It distinguishes this tool from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation and ownership.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage boundaries. Could be improved by mentioning alternatives like 'unsubscribe' vs. 'delete' but overall adequate.

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. The description adds substantive behavioral context: two distinct execution paths (SEC EDGAR/XBRL fast path vs. grounded pipeline), enumerated verdict values, output composition ('grounded or structured actual value with pipeworx:// citation'), and critical semantics distinguishing could_not_verify (with verification_error) from unsupported. No contradictions.

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

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

The description is dense but every sentence earns its place. It leads with trigger phrases, then quickly covers usage, behavior, return values, and caller cautions. The wording is efficient and avoids redundancy with the schema or annotations.

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 covers return values and their semantics, including verdict list and error handling. It also explains the two routing paths and the tool's efficiency advantage over sequential calls. This is sufficient for an agent to correctly select and invoke the tool, and to interpret results properly.

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

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

Schema coverage is 100%, with clear parameter descriptions. The description adds value beyond the schema by explaining tolerance_pct's override behavior and its intended use for hallucination detection ('set 1–2 for hallucination detection'), and by implying the claim parameter's natural-language form with examples.

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: 'natural-language claim verification against authoritative sources' with specific trigger phrases. It distinguishes itself from siblings by describing a combined pipeline that 'Replaces 4–6 sequential calls' and by explicitly partitioning claim types (company-financial vs. other).

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 whenever the agent needs to check whether something a user said is factually correct' and gives concrete examples. It does not explicitly name alternative tools or state exclusions, but the routing logic ('any other factual claim automatically falls through to the grounded pipeline') provides clear contextual guidance.

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