Data Bloomington

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing return format (per-model score, confidence, signals, raw_response + combined view), default model, and the BYO key mechanism for Anthropic, going beyond annotations.

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

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

The description is a single focused paragraph, front-loads the main action, and every sentence contributes essential information without redundancy. It is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description fully explains the return type (per-model fields plus combined view). All parameters are covered in schema and description. The tool's purpose and usage are completely described for effective 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 covers all parameters with descriptions. The description adds practical semantics: explains that _apiKey is only required when 'anthropic' is in models, states default model, and clarifies that context helps disambiguate. This adds meaning beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about a business or topic and scores visibility per model, with specific verb 'probe' and resource 'LLMs'. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on scoring visibility and supporting multiple models.

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

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

The description provides context for use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide an API key. However, it does not explicitly mention when not to use this tool or compare it to alternatives among siblings.

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

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

Annotations declare read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond annotations: returns structured answers with stable pipeworx:// citation URIs, routes across 5,529 tools and 1,455 sources, works on every tier, and makes one fast call. No contradictions with annotations.

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

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

The description is long but front-loaded with the core directive and packed with actionable detail. It is well-structured: preference statement, coverage list, return format, examples, and escalation paths. Minor redundancy exists ('prefer over web search' and 'start here' both convey defaultness), but overall each sentence contributes value.

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

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

Given the tool's simplicity (one primary parameter, no output schema), the description is complete: it covers what the tool does, when to use it, how to phrase questions, what to expect (citations), and when to move to alternatives. No meaningful 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%: all six parameters are aliases of 'question' and clearly described. The description adds illustrative examples of valid queries, which enriches the meaning beyond the schema. Baseline was 3, but the concrete examples and coverage guidance nudge it to 4.

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

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

The description clearly states the tool's purpose: answering factual questions by routing to authoritative structured data with citations. It specifies the verb 'ask', the resource 'Pipeworx', and lists extensive domains. It also differentiates from siblings (ask_pipeworx_grounded, deep_research) and 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?

Explicit guidance is provided: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and trigger phrases like 'what is', 'look up', 'find'. It also states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). This gives clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: it is a live experimental router, candidate improvements may be active, none is currently active, and it is a full working router despite being experimental. This goes beyond the annotations and clarifies the operational status.

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

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

The description is moderately long but every sentence contributes meaningful context: beta status, tool parity, current state, usage instruction, and clarification that it is a full working router. It is structured efficiently with front-loaded key information and no filler.

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

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

Given the tool's complexity as a router with 5,529 tools and no output schema, the description adequately explains its relationship to the stable ask_pipeworx, its current experimental state, and how to use it. It references the stable router's response shape, providing enough context for an agent to understand expected 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?

The input schema provides 100% coverage with descriptions for all six parameters, including the alias relationships. The description does not add parameter-specific details, but the schema already carries the full burden, so a baseline score of 3 is appropriate.

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

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

The description clearly states that ask_pipeworx_beta is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx by being the experimental edge, making the purpose explicit 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 instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It does not list explicit when-not-to-use scenarios, but the context of experimental routing is clearly implied.

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

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

The description goes well beyond annotations, detailing the exact return shape (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also discloses the extra LLM call cost and that it uses only the tool result, which is valuable behavioral context not captured in readOnly/idempotent hints.

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

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

The description is dense and front-loaded, starting with the core purpose, then method, return format, refusal reasons, use cases, and cost tradeoff. Every sentence contributes unique information; no filler or repetition. Despite its length, it is efficiently structured for a complex tool with nuanced behavior.

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

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

The description is exceptionally complete for a read-only tool with no output schema. It explains not only the primary behavior but also edge cases (refusals), return structure, and comparative guidance against ask_pipeworx. It covers success and failure modes fully, leaving no significant ambiguity for the agent.

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

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

Schema description coverage is 100% — all six parameters are documented as aliases for 'question'. The description does not add parameter-level meaning, but it doesn't need to since the schema fully explains the parameters. Baseline of 3 is appropriate as the schema carries the burden.

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: a hallucination-resistant answer mode that extracts answers using only the tool result, returning evidence and refusal reasons. It also distinguishes itself from the sibling ask_pipeworx by emphasizing the grounded nature and 'same routing' with added extraction step.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', listing examples. Also provides an exclusion and alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is clear when/when-not guidance with a named alternative.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: safety (low-confidence short-circuit), closed/dead market handling, wide-spread market warnings, resolution-rule risk, and parent event extraction. No contradictions.

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

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

The description is front-loaded with the purpose but is quite verbose, containing many examples and edge cases. While informative, it could be more concise. Some details (e.g., full fan-out examples) could be streamlined.

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

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

Given the tool's complexity (3 parameters, no output schema, annotations present), the description is remarkably complete. It covers input handling, fan-out logic, response structure, resolver confidence, parent events, news fallback, safety mechanisms, and resolution rules. No significant gaps.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the depth parameter (quick vs thorough) and the market parameter types (slug, URL, question text). It also explains include_raw's effect on response size, 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 researches a Polymarket bet by pulling Pipeworx data, and specifies input types (slug, URL, question text). It is specific but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, missing a clear sibling distinction.

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 use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives classifier and fan-out examples. It does not explicitly state when not to use the tool or mention 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 indicate read-only, open-world, and idempotent behavior. The description adds rich behavioral details: specific financial metrics pulled for companies (10-K revenue, net income, etc.), for drugs (FAERS counts, FDA approvals), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions.

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

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

The description is concise (5-6 sentences) and front-loaded with example queries and a strong usage directive. Every sentence adds value without redundancy, making it efficient for an agent to parse quickly.

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

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

Despite no output schema, the description fully explains return format (paired data + citation URIs) and sorting behavior. It covers input parameters, data sources, and the parallel call nature. For a tool with 2 parameters, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining the meaning of 'company' vs 'drug' types (data sources), providing concrete examples for the values parameter (tickers/CIKs or drug names), and noting sorting behavior. This enriches the semantic understanding beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one call, providing specific data sources (SEC EDGAR for companies, FAERS for drugs). It distinguishes from siblings by explicitly stating preference over sequential single-pack lookups, contrasting with tools like entity_profile.

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

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

The description provides explicit usage guidance with example queries ('compare X and Y', 'X vs Y', etc.) and a strong directive to always prefer this over sequential lookups. It effectively tells the agent when to use the tool and gives alternatives.

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

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

Annotations already declare safe operation (readOnlyHint, idempotentHint). Description adds value by listing return fields (resource_id, name, description, category, update date) and hinting at next steps.

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 purpose, second lists return fields and gives actionable instruction. No wasted words, 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 simple search tool with 3 well-documented parameters and no output schema, the description is sufficient. It covers purpose, return fields, and next steps. Slight lack of pagination detail but schema covers that.

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. Description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Description states verb 'Search', resource 'datasets', and context 'Bloomington Open Data catalog by keyword'. It distinguishes from sibling tools like 'query' or 'search_within' by specifying the catalog domain and return fields.

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?

Implies usage (search datasets then pass resource_id to query/metadata) but lacks explicit guidance on when to prefer this tool over siblings like 'search_within' or 'metadata'.

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

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

Adds substantial behavioral detail beyond annotations: account/plan requirements, latency expectations (15-60s, up to ~90s for thorough), guaranteed no invented answers via gaps[], stable citations fetchable only when resolvable, semantic excerpting, contradictions[] for standard/thorough, and hop field. No contradiction with the readOnly/openWorld/idempotent hints.

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

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

The description is long but every sentence earns its place: account requirement, alternative tools, scope, decomposition, output contents, performance, citation behavior, and depth modes. It is front-loaded with the critical account caveat and contains no redundant filler, though it could be tightened slightly.

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 and lack of an output schema, the description is complete: it explains the findings packet (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[] behavior, contradictions[], hop field, citation resolvability, semantic excerpting, and performance envelopes. It fully covers selection and invocation needs.

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 already provides rich enum semantics for depth (quick/standard/thorough with facet counts and hop details) and natural-language guidance for question. The tool description adds some extra nuance (e.g., paid plan for thorough, latency per depth) but does not materially change parameter understanding.

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

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

The description clearly states it performs grounded multi-source research across Pipeworx's 1455 structured data sources in one call, with specific resource types (SEC, FRED, FDA, etc.). It explicitly distinguishes itself from ask_pipeworx and open-web search, making the purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when to use alternatives ('For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also covers account tier requirements and the fallback if not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns top-N tools with full schemas and curated examples, ready to call directly. This goes beyond annotations by explaining the output format and usability, though it does not detail edge cases like empty results or error handling.

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

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

The description is relatively long but well-structured: it opens with the core purpose, lists example domains, describes the return format, and gives usage advice. It front-loads key information, but there is some redundancy (e.g., multiple aliases for query are already in schema). Still, it earns its keep.

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 (discovery with many potential tasks) and the lack of an output schema, the description adequately explains what the tool returns (top-N tools with names, descriptions, schemas, examples) and its usage context (call FIRST). This is sufficient for an agent to use it correctly.

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

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

Schema description coverage is 100% (every parameter has a description). The tool description does not add meaning beyond the schema; it only mentions 'returns top-N' which is not parameter-specific. Baseline 3 is appropriate as the schema suffices.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools like 'ask_pipeworx' or 'deep_research' that perform different functions. The verb 'discover' matches the name and title.

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

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

The description explicitly advises when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides examples of use cases (e.g., 'look up FDA drug approvals'), giving clear context for invocation.

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, etc. Description adds context about the USPTO PatentsView API sunset (soft-fails), multi-source fan-out behavior, and specific return fields. 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 comprehensive but slightly verbose. It front-loads examples and purpose, but includes detailed data source lists that could be streamlined. Still, every sentence adds value for a complex tool.

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

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

For a tool with 2 params and no output schema, the description covers input constraints, return fields, source details, limitations (patent sunset), and links to resolve_entity. No gaps given the annotations and schema richness.

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. Description adds value by reiterating that type must be 'company' and value can be ticker or CIK, and confirms names are not supported. This goes beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and return fields. It distinguishes itself from sibling tools like resolve_entity by explicitly stating names are not supported.

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

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

Explicitly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and advises using resolve_entity if only a name is available. Provides example queries and clear conditions for 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?

Annotations already provide destructiveHint=true, idempotentHint=true, readOnlyHint=false. Description adds context about clearing stale or sensitive data, but does not contradict annotations. No additional behavioral details beyond use 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?

Two sentences, front-loaded with action and purpose, no filler. 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?

For a simple tool with one required parameter and no output schema, the description is complete. It explains the action, use cases, and relationship to sibling 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 one parameter 'key' described as 'Memory key to delete'. Description adds no further semantics beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key.' The verb 'delete' and resource 'memory' are specific. It also implicitly distinguishes from siblings 'remember' and 'recall' by referencing them.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Provides alternatives by mentioning 'Pair with remember and recall.'

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 read-only, idempotent, non-destructive behavior consistent with annotations. Adds detail on fetching, extracting, and output format (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 concise sentences plus a bullet-like list of uses. Front-loaded with main action, 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?

Covers purpose, behavior, and usage adequately for a simple tool. No output schema, but describes output as ready-to-drop text. Lacks error handling or limitations, but acceptable.

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 3. Description does not add significant new meaning beyond schema descriptions, but contextually it's fine.

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

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

Clearly states it generates a production-ready llms.txt file for any URL, with specific actions (fetches, extracts, emits). Distinguishes from sibling tools like ai_visibility_check by focusing on file 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?

Explicitly lists three use cases (client indexing, own project draft, competitor audit). Does not mention when not to use or alternatives, but context is clear.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it returns active subscriptions by default and lists returned fields, providing helpful 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?

Two efficient sentences: first states action and output fields, second gives usage guidance. No wasted words, 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?

With no output schema, description lists return fields. Parameter is simple with full schema coverage. Provides usage context. Complete 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 covers the single parameter fully (100% coverage). Description implies active-only default, reinforcing schema, but adds minimal extra meaning.

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

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

The description clearly states it lists subscriptions, specifies exact return fields (id, type, params, etc.), and distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly tells when to use: to review monitored subscriptions before adding more or to find an ID for cancellation. Does not mention alternatives but 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=true, idempotentHint=true, destructiveHint=false, establishing the tool as a safe read. The description adds detail on the return fields (schema, metadata) but does not disclose additional behavioral traits beyond what annotations convey.

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

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

The description is a single, well-structured sentence that front-loads the action and key output, with an example. No unnecessary words.

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

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

For a simple read tool with no output schema, the description adequately lists the returned fields (columns, types, row count, category, last-updated). It does not cover error handling or invalid IDs, but the tool's low complexity and annotations make this sufficient.

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

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

Schema coverage is 100% with a clear description of 'resource_id' as a dataset ID with example. The description text echoes this example but adds no new semantic information beyond the schema.

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

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

The description clearly states the verb 'Get' and the resource 'dataset's schema + metadata', listing specific fields returned (columns, types, row count, category, last-updated) with an example resource_id. It distinguishes from siblings like 'datasets' by specifying the exact output, though not explicitly differentiating.

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

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

No guidance on when to use this tool versus alternatives. The description explains what it does but does not specify when not to use it or provide explicit comparison to sibling tools like 'datasets'.

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

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

The description adds substantial behavioral detail beyond the all-false annotations: it discloses rate-limiting (5 per identifier per day), the claim_token return flow, that the tool is free and doesn't count against quota, and that reports are read daily and affect roadmap. This is rich, honest context that goes far beyond what annotations alone convey.

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

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

The description is long but information-dense; every sentence contributes unique guidance. It front-loads the core purpose, then layers usage criteria, exclusions, and behavioral details. It is slightly verbose but appropriately so given the tool's nuanced usage rules.

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 4 params, no output schema, and no useful annotations, the description carries the full burden and succeeds. It explains the return behavior (claim_token issuance and later resolution checking), rate limits, target audience, and how to frame feedback. No significant gaps remain for an agent to misuse 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?

Although schema coverage is 100%, the description adds crucial semantics: it clarifies that claim_token must be passed alone, gives an explicit syntax example, advises 1-2 sentence messages, and emphasizes not pasting end-user prompts. These usage rules meaningfully supplement the schema's field descriptions.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature, data_gap, praise) and distinguishes this tool from siblings by positioning it as the channel for reporting issues about Pipeworx tools, not for general questions or actions.

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 'Use when' conditions for each feedback type and includes an important exclusion: only for tools served by this Pipeworx connection, otherwise file with the other server. It also clarifies ambiguity by pointing to the tool list and instructs users not to paste end-user prompts, making when-to-use and when-not-to-use very 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 mark it as read-only, idempotent, open-world, and non-destructive. The description adds beyond: derivation from CF analytics-engine, no PII, caching behavior (5min-1h), and the self-aggregating nature. No contradiction with annotations.

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

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

The description is a single paragraph with clear front-loading: first sentence states purpose. Each subsequent sentence adds value (use cases, data source, caching). No redundant information; every sentence earns its place.

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

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

Given no output schema, the description explains return values (top tools, top packs, total call volume) and caching. For a read-only analytics tool with one parameter, this is sufficient. Minor gap: no mention of response format or pagination, but acceptable.

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 'window', which includes an enum and description. The description adds meaning: distinguishes shorter vs. longer window use cases. 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 the tool returns 'top tools, top packs, and total call volume' for a specified window. It opens with a specific verb+resource: 'What other AI agents are calling on Pipeworx right now'. This distinguishes it from siblings like 'discover_tools' (discovery) and 'query' (specific questions).

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 enumerates three explicit use cases (discovering hot data sources, confirming popular tool, aligning use case). It provides context for window choice (shorter windows for hotness, longer for steady-state). However, it does not explicitly state when not to use it or mention alternatives from the sibling list.

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

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

Annotations declare readOnlyHint, idempotentHint, and openWorldHint, but the description adds rich behavioral details: scanning top 200 markets by volume, partition checks, fill checks against CLOB depth, and filtering logic. No contradictions; the description greatly enhances understanding of the tool's behavior.

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

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

The description is dense but well-structured: purpose first, then mode details, then advanced checks (semantic anchor, partition filter, fill check). It could be slightly more concise by consolidating some technical details, but every sentence earns its place.

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

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

Given the complexity of arbitrage detection with multiple modes, the description is thorough. It explains the algorithm, response structure, fill check validation, and references sibling tools for additional context. No output schema, but the response format is described sufficiently.

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 each parameter has a description, but the tool description adds significant meaning: explains what event slugs/URLs are accepted, how topic mode searches related events, and the contrast between modes. This goes well beyond the schema's 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 states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies two modes (event and topic) and references a sibling tool (polymarket_fill_risk) for custom sizing, clearly distinguishing it from similar 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 explains when to use each parameter: no args for trending scan, event for per-event checks, topic for cross-event scans. It highlights that cross-event mode catches patterns missed by single-event mode. Absent explicit 'when not to use,' but guidance is clear and actionable.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: caching (1h at KV level), three model families with details, tradeable-edge knobs, response structure including diagnostics, and a 24h-move warning. No contradictions. Goes well beyond annotations.

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

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

The description is lengthy but well-structured: high-level purpose, detailed segments, response fields, then parameter explanations. Front-loaded with the key idea. Some redundancy (model families listed twice), but given the complexity, every sentence earns its place. Efficient for the information density.

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 9 parameters, 3 segments, diagnostic output, and no output schema, the description is remarkably complete. It covers all aspects: what each model does, how knobs filter, response top-level fields, diagnostics, caching, and warnings. No gaps in practical usage guidance.

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 9 parameters. The tool description adds meaningful context beyond the schema, explaining how parameters like min_kelly vs min_partition_leg_kelly interact and the purpose of slippage_pp. Baseline 3, elevated due to added cross-parameter explanations.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan, return), resource (Polymarket markets), and outcome (disagreement opportunities), differentiating it from sibling tools like polymarket_arbitrage which likely handles execution.

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 targets the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also describes configurable knobs for filtering, but lacks explicit 'when not to use' or alternative tools. Strong context but no exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: response structure (tracked, expired, snapshot_dates), decay computation details (daily closes, net of slippage), and explanation of gaps. 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 relatively long but well-organized into response fields and limits. It is front-loaded with the core purpose. Each sentence adds value, though could be slightly more concise.

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

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

Despite no output schema, the description fully details the return structure (tracked, expired, snapshot_dates) and derived fields (first_seen, trend, decay_pp_per_day). It also covers limitations and data context, making it complete for agent decision-making.

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

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

Schema covers 100% of parameters, but the description adds meaningful constraints and defaults (e.g., days lookback default 14, max 30; window families). It clarifies the role of 'window' as snapshot family, which aids selection 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 the tool's purpose: 'Edge persistence and decay telemetry' and explicitly answers the question it addresses, distinguishing it from sibling tools like polymarket_edges. It uses specific verb-resource combinations and domain language.

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 implicit usage guidance by contrasting fresh vs. old edges, implying when to check persistence before trading. It also notes limits (60-day TTL, snapshot gaps). However, it lacks explicit when-not-to-use or alternative tool references.

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

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

Annotations (readOnlyHint:true, openWorldHint:true, idempotentHint:true, destructiveHint:false) indicate safe, non-destructive, possibly varying results. The description complements this by detailing exactly what the tool does: walks the CLOB order-book ladder, returns top_of_book, vwap_fill_price, slippage, and a verdict (clean|degraded|cannot_fill). It also warns about forced_directional_risk, disclosing the key behavioral trait: partial fills can strand the user unhedged. 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 well-structured with clear sections (SINGLE-MARKET, BASKET) and a usage note at the end. However, it is somewhat lengthy (three paragraphs) and includes some redundancy (e.g., repeating default values mentioned in the schema). While every sentence adds information, a more concise version could improve readability without losing content.

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

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

Given the tool's complexity (two modes, multiple return fields) and the absence of an output schema, the description is comprehensive. It details all return fields for both modes, explains the verdict categories, specifies the forced_directional_risk, and provides constraints (max clean notional). This fully equips an agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100% (all four parameters described). The description adds meaningful context beyond the schema: clarifies that size_usd default 1000 means max spend on buys and target proceeds on sells for single-market, and settlement notional for basket; explains side defaults (auto from partition sum for basket); and describes that market and event are mutually exclusive modes. This adds significant value, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, explaining what each does, and explicitly positions itself as a prerequisite check for arbitrage and edge trades, differentiating it 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?

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when not to use it (when theoretical overround may not be capturable) and the risk of partial basket fills converting an arb into an unhedged directional position, offering clear context for when this tool should be consulted.

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

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

Annotations indicate read-only, idempotent, open-world behavior. Description adds detailed behavioral context: response format (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and conditions when spreads are meaningful. 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?

Structured explanation with sections for modes, response, and safety. Each sentence adds value, but could be slightly more concise. Front-loaded with core purpose.

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

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

Explains return fields (prices, top_spreads_pp) and safety fields in detail. Lacks explicit data types but covers key behaviors. Given no output schema, it is reasonably complete.

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

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

Input schema covers all 3 parameters with descriptions. Description adds usage context: explains topic as pre-mapped shortcut with list of values, and that explicit parameters override the topic-mapped side. Provides examples in 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?

Describes specific cross-venue spread computation between Kalshi and Polymarket, distinguishes from sibling tools like polymarket_arbitrage. Clearly states two modes (topic and explicit) and the types of inputs.

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

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

Provides explicit guidance on two modes of use and warns that most pre-mapped topics may not yield actionable spreads. Mentions safety fields that indicate when spreads are meaningless, though doesn't explicitly contrast with alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description's statement 'Returns matching rows as JSON' adds minimal behavioral context. No mention of error handling, rate limits, or pagination behavior beyond the parameters.

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

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

The description is two sentences with no wasted words, front-loading the core purpose and then specifying parameters. It is efficient and easy to parse.

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

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

The description mentions the return format (JSON) but does not elaborate on structure or error cases. Given no output schema, more detail on return values would improve completeness, but the tool's simplicity and annotations mitigate this.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by clarifying that SoQL clauses should omit the leading dollar sign, which is a helpful nuance not present 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 the tool runs SoQL queries against a specific dataset by resource_id, with a specific verb and resource. It distinguishes from sibling tools like 'datasets' (which list datasets) by focusing on querying 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 explains how to filter and paginate with SoQL clauses and limit/offset, but does not explicitly state when to use this tool versus alternatives. The context from sibling names suggests this is for data querying, not metadata or dataset discovery.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping to identifier and the behavior of listing all keys when key is omitted, providing context beyond annotations.

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

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

Four sentences, each serving a purpose: core function, usage, scoping, and pairing. No fluff, well front-loaded with the main purpose.

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

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

For a simple tool with one optional parameter and no output schema, the description covers retrieval, listing, scoping, and related tools completely. 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% and the description reinforces the schema by explaining the key parameter's behavior. No additional parameter semantics needed beyond what schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. It distinguishes itself from siblings remember and forget by specifying its role as retrieval.

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

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

The description explicitly tells when to use the tool: 'look up context the agent stored earlier without re-deriving it from scratch.' It also mentions scoping and pairs with remember and forget, but does not explicitly state when not to use.

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

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

The description reveals that setting mark_read:true modifies state (flags events as read), which contradicts the annotation readOnlyHint=true. This is a direct contradiction between the described behavior and the annotation hint.

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

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

The description is concise (four sentences) and well-structured, starting with the core purpose. It could be slightly shorter but remains informative without unnecessary detail.

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

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

Given the optional parameters and no output schema, the description adequately explains return fields and provides usage notes (polls, alternative access). It is complete enough for an agent to use the tool effectively.

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

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

All five parameters are described in the schema (100% coverage). The description adds value by explaining the mark_read effect and providing example filter values (e.g., 'sec_8k'). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the return fields (source, citation_uri, payload) and filtering options, distinguishing it from potential siblings by focusing on alert retrieval from a persisted feed.

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

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

The description explains filtering by type and since, and how mark_read works to manage read state. It also mentions that 'Polls work fine' and provides an alternative URL for scripts/dashboards, offering usage context. However, it does not explicitly state when not to use this tool versus siblings.

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

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

Annotations already include readOnlyHint, openWorldHint, idempotentHint. The description adds substantial behavioral context: parallel fan-out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and output 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?

The description is fairly concise but includes many examples and parenthetical details. It is front-loaded with example queries. Could be slightly more concise, 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 adequately explains the output (structured changes[] grouped by source, total_changes count, citation URIs). It covers input, behavior, fallbacks, and alternative tool, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining `since` formats in detail with examples, noting `type` is only 'company', and recommending typical usage. This goes beyond the schema's 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 explicitly defines the tool as a change feed for a company over a recent window, with examples of queries and a clear list of data sources. It distinguishes itself from sibling tool entity_profile by contrasting temporal vs static profiles.

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

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

The description provides clear guidance on when to use this tool (temporal changes) and contrasts it with entity_profile for static profiles. It also advises on typical `since` values ('30d' or '1m'). Lacks explicit 'when not to use' but is still helpful.

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?

Disclosures beyond annotations: scoping by identifier, persistence differences (authenticated vs anonymous with 24h expiry). No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Four sentences, front-loaded with main purpose, no wasted words. 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?

No output schema, but description covers storage behavior, scoping, and retention. Fully complete for this simple tool.

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

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

Schema coverage is 100% and already describes key/value with examples. Description adds minimal extra value beyond what schema provides, 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?

Starts with a clear verb+resource: 'Save data the agent will need to reuse later.' Examples (ticker, address, preference) and explicit pairing with recall/forget distinguish it from siblings.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward.' Mentions pairing with recall/forget. Does not explicitly state when not to use, but 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?

The annotations already provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context beyond the annotations: it discloses that each call cascades through several lookup endpoints, that LEI/FIGI enrichment degrades gracefully if GLEIF/OpenFIGI is unavailable, that identifiers are labeled with their source, and that unresolved identifiers are explicitly returned. This substantially increases transparency beyond what annotations reveal.

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

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

The description is relatively long but well-structured with examples, type breakdowns, and fallback behavior. It is front-loaded with practical usage examples. Each section contributes useful information; however, it could be slightly more concise by trimming redundant phrasing (e.g., 'user-spoken' is repeated). Overall, it is efficient for the complexity it covers.

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

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

There is no output schema, so the description carries the burden of explaining return behavior. It does explain that identifiers are labeled with source, unresolved identifiers are explicit, and enrichment degrades gracefully. It covers supported entity types and inputs. However, it does not provide a concrete example of the return structure or possible error cases, which would be helpful for a complex cascading lookup tool. Given the richness of the description despite these omissions, a 4 is warranted.

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

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

The schema already covers 100% of parameter descriptions, including the enum for type and detailed explanations of value formats for company and drug. The description adds examples and some contextual nuance (e.g., ticker vs CIK vs name) but does not fundamentally extend the semantic clarity beyond what the schema already provides. Therefore the baseline of 3 is appropriate.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers required by other tools. It uses specific verbs like 'resolve' and 'look up' and gives numerous concrete examples. It distinguishes itself from siblings by emphasizing it returns the identifiers which other tools require as input, and by positioning it as the first step in such workflows.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which provides a clear use case. It also explains that it replaces 2-3 manual lookups and mentions graceful degradation for enrichment sources. However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it falls short of the highest bar.

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, openWorldHint, and destructiveHint false, but the description adds behavioral details: each entity is probed with ai_visibility_check, results include score/confidence/signal density, and the first entity is treated as the 'subject' for narrative. 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 three sentences, front-loaded with the primary action and use case. Every sentence adds value without redundancy or extraneous detail.

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

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

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density) and covers the tool's complexity (multiple entities, models, API key option, shared context). It is sufficiently complete for an agent to understand the tool's behavior and results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds contextual meaning for the 'entities' parameter (first entry is subject) and explains the 'context' parameter, but does not significantly enrich understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It uses specific verbs ('compare', 'probes', 'ranks') and distinguishes itself from the sibling tool 'ai_visibility_check' by explicitly noting it probes multiple entities and produces a ranked list.

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

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

The description explains when to use the tool: 'Useful for competitive AI-marketing audits' with an example question. It implicitly contrasts with 'ai_visibility_check' (single entity) but does not explicitly mention or exclude alternatives like 'compare_entities' or specify when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: partial failures degrade gracefully, first measurement on a new version can take 5-30s, and sources_failed lists timeouts. This goes 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 long but efficiently structured. It front-loads the core purpose, then provides usage guidance, return details, ecosystem limitations, and behavioral notes. Every sentence adds value, 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?

Despite no output schema, the description details the return contents: summary block fields (is_latest, license, bundle_kb_min, etc.), per-advisory details, links, and alternative versions. It also covers edge cases like partial failures and timeouts, making it complete for a composite 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 both parameters described. The description adds minimal extra: package name accepts scoped packages (already implied by schema description 'npm package name'), and version defaults to latest (already in schema). No significant added meaning.

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

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

The description clearly states the tool's purpose: a composite check for npm packages aggregating data from deps.dev and bundlephobia. It specifies the resource (npm package) and action (scan for safety/popularity/size), distinguishing itself from sibling tools like deps.dev:version for other ecosystems.

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

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

The description explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides clear limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', differentiating from alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds significant behavioral details: max 200K chars with truncation and flagging, embedding model (BGE-base-en), window size (500-char overlapping), similarity measure (cosine), and that every passage has an offset for verification. This goes far 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?

Description is compact (5 sentences), front-loaded with core action. Every sentence adds value: purpose, use case, pairing, technical details. 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?

No output schema exists, but description compensates by explaining return format (passages with offsets and similarity scores). It covers technical behavior, limits, and truncation. Also mentions pairing with another tool. Complete for a tool of this complexity.

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

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

Schema description coverage is 100% (all three parameters documented in schema). Description does not add new parameter-level information beyond what schema provides, though it recontextualizes 'text' as 'already pulled' and gives query examples. At high coverage, 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?

Description clearly states 'Semantic search INSIDE a fetched record' with verb-resource pair. It distinguishes from siblings by specifying it operates on already-fetched text, contrasting with tools that fetch or search externally. The phrase 'Pairs with ask_pipeworx_grounded' further differentiates.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefit (saves context, returns only passages that matter). Mentions pairing with a sibling tool. However, does not explicitly list when NOT to use or provide exhaustive alternatives among siblings.

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

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

The description adds behavioral context beyond annotations, such as the need for OAuth, delivery limits (SMS 10/day cap), and that webhook secret is returned once. Annotations indicate mutation (readOnlyHint=false) and idempotency, which aligns with the 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?

The description is front-loaded with the core purpose and is well-structured, but it is somewhat lengthy. However, every sentence adds value, so it earns a 4.

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

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

Given no output schema, the description explains the return (subscription ID) and covers all aspects: prerequisites, types, delivery channels, and limitations. It is thoroughly complete for a complex tool with nested objects.

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 description elaborates on parameter semantics with examples for each subscription type and delivery channel, adding meaning beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It uses specific verbs and resources, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description explains when to use the tool (to set up alerts) and prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist). It does not explicitly state when not to use it but provides sufficient context given the sibling tools.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds behavioral details: it returns category-bucketed example questions with exact tool+argument shapes, drawn from the live catalog, and explains the effect of omitting vs. providing a topic. 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 longer but well-structured: starts with common queries, explains output, then usage guidance. Every sentence adds value, though some repetition of categories could be trimmed. Front-loaded with the key purpose.

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

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

Without an output schema, the description fully explains the return type (category-bucketed example questions with tool+argument shape) and source (live catalog of thousands of tools). It also references meta-tools, making it complete for the agent to decide to invoke.

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

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

The input schema already describes the `topic` parameter with valid values and default behavior (omit for cross-category). Schema coverage is 100% so baseline is 3. The description adds narrative context by listing categories and reinforcing the logic, providing incremental value.

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

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

The description clearly states it is the onboarding entry point for learning what to ask Pipeworx, listing specific example queries and its output of category-bucketed example questions with tool and argument shapes. It distinguishes itself from sibling tools like ask_pipeworx by positioning itself as the first step.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use guidance. It also implies alternative uses like when the user asks for ideas or getting started, and mentions focusing via topic parameter.

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 context beyond annotations: ownership enforcement, deactivation (not deletion), and historical event availability. Annotations indicate destructiveHint=false and idempotentHint=true, which align with the description. No contradictions.

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

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

The description is concise (two sentences) and front-loaded with the core action. Every sentence provides necessary information without redundancy.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description covers all necessary behavioral aspects: purpose, ownership, deactivation, and historical data retention. It is fully complete for effective use.

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

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

Schema coverage is 100% for the single 'id' parameter, which already describes it as a 'Subscription id (uuid) returned by subscribe.' The description adds little parameter-specific detail beyond 'by id,' but the baseline of 3 is appropriate given the schema's completeness.

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 the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by emphasizing ownership enforcement and deactivation 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 specifies that ownership is enforced ('you can only cancel your own subscriptions'), indicating when it is appropriate to use. It also explains that the row is deactivated, not deleted, which guides usage expectations. However, it does not explicitly mention alternatives or when not to use this tool.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by detailing return semantics: the set of verdicts, the meaning of 'could_not_verify' (including verification_error{stage,detail} and the warning not to treat it as evidence), and the distinction with 'unsupported'. It also discloses the routing behavior and evidence requirement, giving agents critical behavioral knowledge not available from 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 longer than average but almost every sentence carries information. The initial list of query phrasings is slightly redundant but useful for pattern matching, and the 'IMPORTANT for callers' callout is necessary. It is front-loaded with purpose and usage, then provides structured details on return values and 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?

Given the tool's complexity, two parameters, and no output schema, the description supplies the essential context: verdict outcomes, routing logic, evidence/citation behavior, and error-state semantics. The description is sufficiently complete for an agent to understand both function and failure modes without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful value: it explains how tolerance_pct interacts with claim wording, provides the default cap of 5, and clarifies the override use case for hallucination detection. It also supplies concrete examples for the claim parameter beyond the schema's 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 opens with explicit natural-language query forms and states the core action: 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from siblings by specifying the two pipeline paths (SEC EDGAR/XBRL for company-financial claims, grounded pipeline for all other facts), making the tool's scope 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?

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates between company-financial and other claims, and explains the benefit over sequential calls ('Replaces 4–6 sequential calls'), giving the agent clear context for choosing this tool over alternatives.

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