Data Michigan

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds that probing Workers AI is free, Anthropic is paid via user's key, and returns per-model data. 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?

Single, focused paragraph with action first, then details, then use cases. Every sentence is informative.

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 format (per-model {score, confidence, signals, raw_response} + combined) despite no output schema. Covers all 4 parameters, required fields, and use cases comprehensively.

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

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

Schema coverage is 100%, but description adds value: default model, free vs paid, and that context disambiguates. Enriches beyond schema descriptions.

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

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

Clearly states it probes LLMs for knowledge about entities and scores visibility (0-100) per model. Distinguishes from similar sibling 'scan_competitor_ai_presence' by being broader and providing scores.

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

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

Explicit usage contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also explains when to use _apiKey for Anthropic. Could mention when not to use (e.g., if entity is too niche), but still clear.

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

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

Annotations already cover the read-only, non-destructive, idempotent nature. The description adds meaningful behavioral context: it acts as a router (5,462 tools, fills arguments), returns citation URIs, and works on all tiers in one fast call. This goes beyond the annotations without contradicting them.

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

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

The description is long but every sentence provides actionable guidance: when to use, when not, examples, and alternatives. It is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and structured logically. Slightly verbose but highly informative.

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 discloses the core return characteristics (structured answer with pipeworx:// citation URIs) and the tool's scope. It covers the main decision points for an agent: what it does, which domains it covers, and when to escalate. Minor gaps like error handling or exact answer format are acceptable for a router tool.

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

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

The input schema has 100% coverage for all six parameters (all aliases for question). The description provides examples but does not add new parameter semantics beyond the schema's own description of 'natural language question with aliases'. Baseline of 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool routes factual questions to thousands of verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique role obvious.

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

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

Explicitly instructs to prefer over web search for a wide range of factual topics, provides trigger phrases, gives concrete examples, and names alternatives (ask_pipeworx_grounded, deep_research) with when to step up. This is exemplary usage guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable experimental context: live candidate routing improvements, current inactive status, and the fact that results are compared to the stable router. This goes far beyond the annotations and sets accurate expectations for 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 four sentences and each sentence carries useful information: identity, current state, usage, and clarification. It is slightly verbose with the specific retirement date, but that detail adds credibility and does not feel wasteful.

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

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

The description fully contextualizes the tool: what it is, how it relates to its sibling, when to use it, and its experimental nature. Without an output schema, it still communicates the response shape by reference to ask_pipeworx, making it complete for an AI agent.

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

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

Schema coverage is 100%, with the 'question' parameter and its aliases fully documented. The description adds no parameter-specific details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states it is a 'universal router' with 5,462 tools, and explicitly positions it as the beta version of ask_pipeworx, distinguishing it from its stable sibling. The verb 'ask' and resource 'Pipeworx' are implied through the name and description, and the scope is well-defined.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the comparison against the stable router, giving clear when-to-use guidance. It also clarifies it is not a fallback, preempting potential misuse.

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 substantial context beyond these: extraction is grounded only in tool results, explicit refusal reasons are enumerated, evidence includes verbatim quotes, and there is an extra LLM call cost. This enriches the behavioral profile without contradicting annotations.

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

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

The description is dense but well-structured, front-loading the core purpose and then covering mechanics, return format, refusal reasons, usage guidance, and cost tradeoff. Every sentence provides unique value; 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?

With no output schema, the description fully covers return values on success and failure, lists all possible refusal_reason values, explains the routing and extraction process, and distinguishes from siblings. It is 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%, including aliases for the single required 'question' parameter. The description mentions the tool accepts natural language questions and fills arguments, but does not add new 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?

The description states the tool is a 'Hallucination-resistant answer mode' with a specific function: route through tools, fetch data, and extract only what the tool result contains. It clearly distinguishes itself from sibling ask_pipeworx by emphasizing extraction and refusal behavior, making its purpose unmistakable.

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

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

Explicitly specifies when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Provides a clear alternative: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost. This is excellent guidance.

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

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

Beyond annotations (readOnlyHint, etc.), describes resolver contract, parent event extractor, news fallbacks, low-confidence blocking, wide-spread illiquidity, and resolution-rule risk. 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?

Very detailed and structured but quite verbose. While every section earns its place, the length may overwhelm an agent. Could be trimmed while retaining key points.

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 comprehensively explains response shapes, edge cases (closed markets, low confidence), and safety mechanisms. Covers all likely agent questions.

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?

Parameters are fully covered in schema (100% coverage). Description adds concrete examples (e.g., slug 'will-bitcoin-hit-150k'), depth behavior, and include_raw recommendation. Adds meaningful context 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?

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Provides specific use cases ('should I bet on X') and differentiates from siblings through detail on classifiers, fan-out, and response shapes. No other tool in the list covers this exact functionality.

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 for' three scenarios and warns about inspecting market_match_confidence. Gives depth parameter guidance. Lacks explicit 'when not to use' or direct sibling comparisons, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. Description adds valuable behavioral context: handles off-calendar fiscal years, returns paired data with citation URIs, and replaces many sequential lookups. 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 reasonably concise given the complexity, front-loading with usage patterns. A few words could be trimmed, but it effectively communicates key points without waste.

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

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

Given no output schema, the description adequately explains return format (paired data, citation URIs, sorted results). It covers data sources for both types and edge cases like fiscal year handling, making it complete for an AI agent.

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

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

Schema coverage is 100%, but description adds significant meaning: for company, it pulls specific financials from SEC; for drug, FAERS data. It clarifies that values can be tickers/CIKs or drug names, and limits count to 2-5.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs, with trigger phrases like 'Compare X and Y' and 'head to head'. It explicitly distinguishes from sequential single-pack lookups, addressing sibling differentiation.

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

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

Explicitly says to prefer over sequential lookups and describes when to use for company vs drug. Provides examples of queries that trigger it. However, it does not specify when not to use (e.g., if more than 5 entities or non-company/drug types).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is covered. The description adds value by specifying return fields and the chaining pattern, which are not in annotations. However, it does not disclose rate limits or pagination behavior beyond schema.

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, each purposeful. The first defines the action, the second specifies the output and a usage hint. It is front-loaded and contains no redundant or irrelevant information.

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

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

Given the tool's simplicity (3 parameters, no output schema, strong annotations), the description sufficiently covers purpose, return values, and next steps. No additional context is necessary 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 well-described parameters. The description adds context by explaining the 'query' parameter as a keyword and implies pagination via limit/offset, but does not significantly extend beyond the schema's existing descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches the Michigan Open Data catalog by keyword and lists the specific return fields (resource_id, name, description, category, update date). This specific verb-resource combination distinguishes it from sibling tools, which are unrelated (e.g., deep_research, bet_research).

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

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

The description implies usage for searching Michigan open data and hints at chaining with 'pass the resource_id to query/metadata', but it does not explicitly state when not to use it or differentiate from siblings like 'query'. Usage context is clear but exclusions are missing.

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, non-destructive, and idempotent behavior, but the description adds substantial context: account/payment requirements, latency expectations, return-finding structure (evidence, confidence, source, gaps[]), citation resolvability, semantic excerpting, and contradiction detection. This goes well beyond what annotations convey, and there is no contradiction with the annotation set.

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 provides value; critical details like account requirements and sibling alternatives are front-loaded. However, it is a single dense paragraph with many parenthetical asides, making it slightly less scannable than ideal. Still appropriately sized for a complex tool with no output schema, so a 4 is warranted.

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 packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop field. It also covers latency, account tiers, and edge-case behaviors (e.g., empty gaps for non-structured topics). This leaves the agent well-equipped to select and invoke the tool correctly.

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

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

Input schema covers 100% of parameters (question, depth), so baseline is 3. The description further explains depth semantics by detailing 'quick=3 (single hop)', 'standard=5' with gap recovery and contradictions scan, and 'thorough=8' with an extra iterative hop. This enriches the parameter meaning beyond the schema's enums, 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: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources...' and distinguishes it from siblings by noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups. It uses specific verbs and resources, making the tool's identity 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 'For a single lookup use ask_pipeworx' plus advice to prefer ask_pipeworx for breaking/current-news topics. It also mentions using ask_pipeworx if not signed in, giving clear exclusions and alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotent=true, indicating safe, idempotent read. The description adds valuable behavior: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations by explaining the output format and usability, with 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 (3 sentences) and front-loaded: first sentence states purpose, second lists domains, third explains return format and usage guidance. Every sentence adds value with no redundancy or 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 (search for tools with return of schemas), the description fully covers usage context ('call this FIRST'), return structure (names, descriptions, schemas, examples), and parameter aliases. No output schema exists, but the description adequately explains what is returned.

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% (6 parameters fully described). The description mentions the main 'query' parameter and its aliases, but does not add substantial meaning beyond the schema. Baseline 3 is appropriate since the schema already provides adequate documentation.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains, making the scope explicit. The verb 'discover' and resource 'tools' are specific, and sibling tools are distinct (e.g., specific tools like query, datasets), so differentiation is clear.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it, though it does not explicitly state when not to use it (e.g., for a single direct query). Still, the guidance is strong and practical.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds extensive behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), details returned fields, notes patent sunset (May 2025 soft-fail), and specifies no name support. 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 compact (around 5 sentences), front-loaded with examples and intent, no redundant text. Every sentence adds value, explaining sources, output fields, and constraints.

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

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

Despite no output schema, the description lists all returned data categories (cik, filings, fundamentals, patents, news, LEI) and notes limitations (patent sunset, name unsupported). For a tool with only 2 parameters, this is highly complete and actionable.

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 (type and value) fully described. The description echoes that names are not supported and provides examples, but adds no new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description starts with clear example queries and states it returns a full cross-source profile of a US public company in one parallel call. It explicitly distinguishes from siblings by advising preference over chaining single-pack lookups.

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

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

The description provides multiple example inputs, directly states 'ALWAYS PREFER over chaining...' for holistic views, and explicitly notes that names are not supported, directing to use resolve_entity first. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already set destructiveHint=true, so the description's 'Delete' is consistent. It adds context about clearing sensitive data, which is a behavioral trait beyond the annotation's binary flag.

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

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

Two sentences with no wasted words. The verb and object are front-loaded, and usage guidance follows efficiently.

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

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

For a simple delete operation with one parameter, the description covers purpose, usage guidance, and pairing with sibling tools. No output schema needed given the action is straightforward.

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 with description 'Memory key to delete'. The description doesn't add new parameter info, so baseline 3 is appropriate given 100% schema coverage.

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

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

The description starts with 'Delete a previously stored memory by key', which is a specific verb and resource. It clearly distinguishes from siblings (remember and recall) by focusing on deletion.

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'. It also names sibling tools as alternatives for storing/recalling.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds process details ('fetches the page, extracts title/description/key links, emits standard format'), providing useful behavioral context beyond annotations.

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

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

The description is concise (3-4 sentences), front-loaded with the main purpose, and every sentence adds value. No redundant or extraneous information.

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

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

For a simple tool with 2 parameters and no output schema, the description covers what it does, how it works, output format, and use cases. It is fully adequate.

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

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

Schema description coverage is 100%, so parameters are already documented. Description does not add meaning beyond the schema (e.g., default values for max_links, URL format). 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 it generates a production-ready llms.txt file for any URL, specifying the verb, resource, and scope. It explicitly mentions target audience and output format, making the purpose unmistakable.

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

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

The description provides specific use cases (get client site indexed, draft for own project, audit competitor), giving clear when-to-use guidance. However, it does not explicitly state when not to use or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, indicating a safe, read-only operation. The description adds value by specifying the output fields and default behavior (active subscriptions only), which is consistent with annotations. 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 two sentences, front-loads the primary purpose, and provides essential usage guidance without extraneous text. 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 list tool with one optional parameter and no output schema, the description adequately covers the return fields and usage context. No additional information (e.g., pagination) is necessary given the tool's simplicity and the annotations covering safety.

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 single boolean parameter described as 'Include cancelled subscriptions in the response (default false).' The description does not add additional semantics beyond what the schema already provides; the use of 'active' in the description implies the default filter matches the parameter meaning. Baseline score of 3 for high coverage 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 verb 'List' and the resource 'the caller's active subscriptions', specifying the return fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe and unsubscribe, which have different purposes.

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

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

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear usage context and implies alternatives (subscribe, unsubscribe) without overcomplicating.

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 no destructive behavior. The description adds value by specifying the exact metadata returned (columns, types, row count, etc.) and the data source (Michigan Open Data). 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?

Single sentence, front-loaded with the verb and key information. No extraneous words; every part 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?

Description adequately covers purpose, parameter, and return fields. With no output schema, it provides sufficient detail for a simple metadata retrieval tool. Could mention lack of pagination or error cases, but not required given simplicity.

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

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

Schema coverage is 100% with a clear description for resource_id. The tool description echoes the parameter with an example, adding minimal context about the data source. 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 states a specific verb ('Get') and resource ('Michigan Open Data dataset's schema + metadata') and lists output fields (columns, types, row count, category, last-updated). It clearly distinguishes from sibling tools, which are unrelated or serve different purposes.

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

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

The description implies usage context (need a resource_id, likely obtained from 'datasets' tool), but does not explicitly compare to alternatives or state when not to use. Thus, clear 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 are all false hints, so the description carries full burden. It discloses the claim_token flow for anonymous filing, rate limiting ('5 per identifier per day'), that it is free and doesn't count against quota, and that the team reads digests daily. This goes far beyond the minimal annotation info.

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 typical, but every sentence serves a purpose given the tool's complexity (token flow, exclusions, rate limits). It is front-loaded with the core purpose before diving into constraints, making it efficiently scannable despite length.

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

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

No output schema exists, yet the description covers return behavior (claim_token, later status read), constraints, exclusions, and usage guidance. Given the nested object, 4 parameters, and unusual claim_token workflow, this description is fully complete for an agent to invoke and follow up correctly.

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

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

Schema covers 100% of parameters, but description adds meaningful context: how to phrase message ('Describe the issue in terms of Pipeworx tools/packs', 'don't paste the end-user's prompt') and the claim_token round-trip syntax ('pass it back later as pipeworx_feedback({claim_token:...})'). This enriches schema descriptions without redundancy.

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 first sentence states a specific verb ('Tell the Pipeworx team') and resource ('something is broken, missing, or needs to exist'), clearly distinguishing it from siblings like ask_pipeworx which are for getting information. It also enumerates feedback types (bug, feature, data_gap, praise) directly.

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

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

Provides explicit when-to-use conditions ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed...') and an explicit exclusion ('if the tool came from a different MCP server... file it with that server instead'). Even advises on phrasing, making it a model of usage clarity.

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 detail: data source (CF analytics-engine), no PII, caching (5min-1h), and aggregate nature. No contradictions.

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

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

Two sentences cover purpose, use cases, and technical details. Front-loaded with the essential output, then structured with numbered use cases. Every sentence is informative and concise.

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

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

Despite no output schema, the description explains what is returned (top tools, top packs, total call volume) and caching behavior. The single optional parameter is thoroughly documented in schema and description. Complete for a read-only, idempotent 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%, so the baseline is 3. The description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' providing decision guidance beyond the enum names.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a specified window. It explicitly lists three use cases, distinguishing it from sibling tools like 'discover_tools' or 'ask_pipeworx' which serve different purposes.

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

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

The description provides clear guidance on when to use the tool with three enumerated scenarios. It lacks explicit exclusions or alternative tools, but the context is sufficient for an agent to decide.

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

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

Discloses internal logic (monotonicity checks, partition checks, semantic anchor, partition filter, fill check) beyond the annotations. Annotations indicate readOnly, openWorld, idempotent, non-destructive; description adds context on how results are computed and when signals are unreliable.

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?

While the description is lengthy, it is well-structured with labeled sections and front-loaded with the main purpose. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (multiple modes, response details, fill check), the description covers everything: input modes, output fields, internal filters, and failure conditions. No output schema exists, but the description adequately explains the return structure.

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 both parameters. The description adds further meaning: example slugs, recommended usage (e.g., 'event' recommended), and what happens in each mode, significantly enhancing understanding beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, making the purpose very clear and differentiating from sibling tools.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also explains when not to trade (if realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing, providing 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?

The description extensively discloses behavioral traits: caching at 1h KV level, calculation of edge net of slippage, Kelly sizing, tradeable-edge filters, segment classification, and diagnostics for empty outputs. This goes well beyond the annotations (readOnlyHint, etc.), which are minimal, providing all necessary behavioral context.

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

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

The description is long but well-structured with sections and bullet-like content. It front-loads the purpose and segments, and every sentence adds value. A slight reduction in verbosity could improve conciseness, but the organization compensates.

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, absence of output schema, and many parameters, the description is remarkably complete. It explains the response structure (by_segment, diagnostics), caching, edge details, and filter logic (tradeable-edge knobs). It leaves no major gaps for an AI agent to interpret the tool's 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?

All 9 parameters are described in the schema, and the description adds rich contextual meaning such as how 'min_kelly' filters small opportunities, 'slippage_pp' affects edge calculation, and 'min_partition_leg_kelly' applies to partition legs. The description explains the impact of each parameter beyond the schema's basic description.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings by specifying three model families and segments, and explicitly mentions it is built for discovering betting opportunities without paging through hundreds of markets.

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

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

The description provides clear context for when to use the tool (e.g., 'what should I bet on today'), and explains caching behavior and configurable knobs. However, it does not explicitly state when not to use this tool or provide direct comparisons to sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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, etc. The description adds substantial behavioral context: details the three response arrays (tracked, expired, snapshot_dates), explains field meanings (trend, decay_pp_per_day, lifespan_days), and mentions limitations like the 60-day TTL and daily closes. 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 informative but slightly verbose. It front-loads the core purpose and then details response structure. Every sentence adds value, though the response format details could be more concise. Overall, it is well-organized and efficient.

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

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

Given the lack of an output schema, the description thoroughly explains the return values (tracked[], expired[], snapshot_dates[]) and their fields. It also mentions limitations (60-day TTL, daily closes). This provides a complete picture for an AI agent to understand the tool's output 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%, and the description adds minimal value beyond schema: it restates default and max for 'days' and default for 'window'. The description does not introduce new parameter meanings or constraints that are absent from the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current 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 implicitly guides usage by contrasting fresh wide edges vs. old ones, suggesting when this tool is valuable. However, it does not explicitly state when not to use it or provide alternatives from the sibling list, leaving some ambiguity for an AI agent.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond by detailing the simulation behavior (walks the ladder, returns verdict like clean/degraded/cannot_fill) and warns about forced directional risk. 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 lengthy and dense with information, which may hinder quick parsing. While well-structured with sections and front-loaded purpose, it could be more concise. Some repetition (e.g., side options in both description and schema) adds length.

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

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

Despite lacking an output schema, the description thoroughly lists return fields for both modes (e.g., top_of_book, vwap_fill_price, profit_usd, forced_directional_risk). It covers edge cases, defaults, and warnings, making it complete for agent decision-making.

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

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

Schema description coverage is 100%, but the description adds value by explaining defaults (side auto for basket), interpreting size_usd differently for single-market vs basket, and clarifying the side options. This helps agents understand parameter semantics 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from siblings by specifying it should be used before acting on signals from polymarket_arbitrage or large trades from 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 also warns against thin books and partial fills converting arb into directional risk, helping the agent decide when to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it details two cases for compatibility_warning (non-equivalent bet shapes or semantically unrelated events), explains temporal_alignment, and describes skipped_cross_type/subtype counters. 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-structured: opening statement, mode explanation, response description, safety field details, and a cautionary note. Every sentence adds value for a complex tool. Could be slightly more concise, but the density of useful information justifies the length.

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

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

Given the complexity (cross-venue, multiple modes, safety fields), the description covers nearly all aspects: usage modes, input combinations, response structure (spread list, top_spreads_pp), safety flags (compatibility_warning, temporal_alignment, skipped counters). No output schema exists, but the description compensates by explaining the return structure.

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

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

Schema coverage is 100% with all three parameters documented. The description adds meaning beyond schema by listing the 10 pre-mapped topics with examples, explaining that explicit tickers override topics, and providing examples like 'fed' and 'btc'. It also clarifies optionality and interaction between parameters.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison rather than single-venue arbitrage. The two modes (topic shortcuts and explicit tickers) are explicitly outlined.

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 topic mode (pre-mapped shortcuts) vs explicit mode, and warns that most pre-mapped topics currently return compatibility warnings, advising agents not to expect tradeable spreads. Safety fields (compatibility_warning, temporal_alignment) further guide interpretation of results.

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

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

The description notes that the query returns 'matching rows as JSON', adding some behavioral detail beyond the annotations (readOnlyHint=true, destructiveHint=false). However, it does not disclose additional traits such as rate limits, pagination default (1000), or behavior with missing resource_id. Given that annotations already cover safety, this is adequate but minimal extra value.

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

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

The description is extremely concise: two sentences. The first sentence states the action and key identifier, the second lists the parameters. No wasted words; all information is front-loaded.

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

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

Given the tool's complexity (7 parameters, no output schema), the description covers the essential aspects: the query language, parameters, and return format (JSON). It doesn't describe errors or edge cases, but for a read-only query tool with clear schema descriptions, this is sufficient to invoke correctly.

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

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

With 100% schema description coverage, baseline is 3. The description adds value by explaining that SoQL clauses should not include the leading $, combining with limit/offset, and providing examples. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: running a Socrata SoQL query against a Michigan Open Data dataset by resource_id. It specifies the verb 'Run', the resource 'Socrata SoQL query', and the scope 'against a Michigan Open Data dataset by resource_id', distinguishing it from unrelated sibling tools like 'datasets' or 'ask_pipeworx'.

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

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

The description provides clear context for usage by listing acceptable parameters (where/select/group/order/limit/offset) and noting the SoQL syntax without leading $. While it does not explicitly state when not to use this tool or name alternatives, the context is sufficient for the intended use case of querying a specific dataset.

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 give readOnlyHint and destructiveHint. The description adds scoping to identifier (IP/key/account) and purpose (retrieve previously saved via remember). It does not cover return format or error behavior but adds useful context beyond annotations.

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

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

The description is two sentences covering action, scope, and pairing. Every sentence is informative, no redundancy. Front-loaded with the core functionality.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is fairly complete. It defines inputs, behavior, and context. Could mention return format for missing keys, but not essential.

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 explains the parameter behavior (omit to list) which is already in the schema description. No additional parameter meaning is added beyond what the schema provides.

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

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

The description clearly states the tool retrieves a saved value by key or lists all keys, distinguishing it from remember and forget explicitly. Verb 'retrieve' and resource 'memory key' are specific.

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 (look up context stored earlier) and how to use (omit key to list). It mentions pairing with remember/forget as alternatives. It lacks explicit 'when not to use' but provides sufficient guidance for typical scenarios.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds context about the mark_read side effect (flagging events as read) and the persistent feed, which is beyond what annotations provide. 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, with four sentences that front-load the main purpose and each sentence adds unique value. No filler or redundancy.

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

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

For a simple retrieval tool with comprehensive schema and annotations, the description adequately explains the output contents and the effect of parameters. It could mention pagination or error handling, but the provided information is 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%. The description adds meaning by providing an example filter for type ('sec_8k'), explaining the mark_read effect, and noting the ISO timestamp format for since. This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the resource (subscription feed) and what it returns (source, citation_uri, raw payload). It distinguishes from siblings like 'list_subscriptions' by focusing on fired events rather than subscription management.

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 mentions that polling works fine and points to an alternative HTTP endpoint for scripts/dashboards, providing clear usage context. It also explains the mark_read behavior for managing read state. However, it does not explicitly compare to siblings like 'query' or 'subscribe'.

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

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

Despite annotations already indicating a safe, read-only, idempotent tool, the description adds rich behavioral details: it fans out to multiple sources, has GDELT→GNews fallback, notes the PatentsView API sunset, explains the since parameter format, and describes the return structure. This goes well beyond annotations.

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

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

The description is dense but well-structured: example queries upfront, then the fan-out logic, parameter details, and return structure. Each sentence is substantive, though a minor tightening could be possible. Overall, it's efficient and front-loaded.

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

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

Given the tool's complexity (multiple sources, fallback, parameter options, no output schema), the description is remarkably complete. It covers each data source's behavior, failure modes, parameter semantics, and return format, and even advises when to use an alternative. 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%, baseline 3, but the description adds significant value: it explains since format with examples ('2026-04-01', '7d', '30d'), recommends typical usage ('30d' or '1m'), and clarifies value can be ticker or CIK. This greatly aids 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 defines the tool's purpose as a change feed for a company, covering SEC filings, news, and patents. It provides example queries and distinguishes itself from the sibling tool entity_profile.

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

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

The description explicitly states when to use this tool (e.g., 'what's new with X') and when not to ('Use entity_profile instead when you want the static profile'), giving clear guidance and alternatives.

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

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

Adds important behavioral context beyond annotations: authenticated users get persistent memory, anonymous sessions expire in 24 hours. Does not contradict 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 with no wasted words: front-loaded purpose, then usage, then storage details. Efficiently conveys all essential information.

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

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

With no output schema, the description doesn't mention return values, but for a simple write operation this is acceptable. Covers key use cases and persistence details sufficiently for an agent.

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

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

Schema already describes both parameters well. Description adds concrete key examples (subject_property, target_ticker) and clarifies value is any text, providing marginal extra 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 the tool saves data for reuse across conversations/sessions, using a key-value pair scoped by identifier. It distinguishes this from sibling tools recall and forget.

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

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

Explicitly tells when to use: when agent discovers something worth carrying forward to avoid re-lookup. Also mentions pairing with recall and forget for lifecycle management.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: internal cascading through multiple lookup endpoints and the inclusion of citation URIs in results, which goes beyond the structured annotations.

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

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

The description is front-loaded with purpose and uses a clean structure with examples and SUPPORTED TYPES. It is somewhat long, but every sentence contributes useful information, from accepted inputs to behavioral notes, without fat.

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 two-parameter tool with no output schema, the description is remarkably complete: it covers input types, output fields, citation URI format, disambiguation behavior, and even efficiency rationale. Combined with strong annotations, the agent has enough context to select and invoke this 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?

Even though the schema covers both parameters, the description enriches parameter understanding by specifying exact return fields for each type (e.g., ticker + CIK + company_name, RxCUI + ingredient + brand) and clarifying input flexibility (auto-disambiguation for companies). This adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose with a specific verb ('resolve') and resource ('NAME to canonical/official identifier'). It provides concrete example queries and explicitly distinguishes this tool as the go-to for name-to-ID lookups, setting it apart from sibling tools.

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

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

It gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types and accepted input forms, but does not mention when not to use it or point to alternative tools for different needs.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant value by detailing the probing process, ranking, and output components (score, confidence, signal density), which are not covered by annotations.

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

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

Four sentences, no redundancy. Front-loaded with the main purpose, each sentence contributes essential information (what it does, how it works, use case, output).

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?

Adequately explains output format and use case. Lacks details on error handling or rate limits, but annotations (readOnly, idempotent) mitigate the need. The sibling list shows distinct tools, reducing confusion.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds nuance by noting the first entity is treated as the 'subject' for narrative, which clarifies usage 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?

Clearly states the tool compares AI visibility across multiple entities side-by-side, specifying the action (compare), resource (AI visibility), and scope (multiple entities). It distinguishes from sibling ai_visibility_check by focusing on comparison and ranking.

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

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

Provides explicit context for competitive AI-marketing audits and an example question. However, it does not explicitly exclude alternatives like compare_entities or state when not to use this tool, leaving slight ambiguity.

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

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

Adds context beyond annotations: fans out across two external services, describes graceful degradation for bundlephobia timeouts, and lists fields in the return summary.

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?

Concise yet thorough; front-loaded with purpose, then specifics. Every sentence adds value without redundancy.

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

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

Despite no output schema, description thoroughly documents return fields, failure modes, and links. Covers all relevant context for a single-call 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% but description adds value: clarifies package accepts scoped names, version defaults to latest, and explains the role of each parameter in the composite check.

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's a composite npm package check covering license, advisories, version history, and bundle info. Distinguishes from siblings by specifying 'npm package' and the specific data sources.

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

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

Explicitly says when to use: for questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. Notes that non-npm ecosystems should use deps.dev directly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. No contradictions.

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

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

The description is a single paragraph but packs essential information efficiently. It is front-loaded with purpose. Minor redundancy (e.g., 'cap is 200K chars' could be more concise) but overall well structured.

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

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

Given no output schema, the description explains return values (top-N passages with offsets and scores). It covers embedding model, windowing, truncation, and pairing with sibling tools. Complete for a tool of this complexity.

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

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

Schema coverage is 100%. The description adds significant value beyond the schema by explaining 'text' as the document to search, giving example queries for 'query', and clarifying 'limit' range and default. Examples contextualize usage.

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

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

The title and first sentence clearly state the tool does semantic search inside a fetched record. It distinguishes from siblings by explicitly pairing with 'ask_pipeworx_grounded' and specifying use case for large documents.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with 'ask_pipeworx_grounded' as an alternative workflow. This provides clear guidance on when and how 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 adds significant behavioral details beyond the annotations, including authentication requirements (OAuth account), rate limits (10 SMS/day), delivery channel specifics (webhook signing and auto-disable), and return value (subscription ID). These complement the annotations (readOnlyHint, openWorldHint, etc.) without contradiction.

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

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

The description is well-structured with front-loaded purpose, but it is somewhat lengthy due to detailed examples and explanations. However, every sentence adds value, so it remains effective without unnecessary fluff.

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

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

Given the tool's complexity (3 parameters, one nested object, no output schema), the description is remarkably complete. It covers all supported types, delivery options, prerequisites, return value, and behavioral nuances (e.g., webhook auto-disable, SMS cap), leaving no obvious gaps for an agent to misinvoke.

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 the input schema has 100% description coverage, the tool description enriches each parameter with examples, constraints (e.g., phone verification, webhook secret), and type-specific filters. This goes beyond the schema's basic descriptions, providing actionable guidance for parameter usage.

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

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

The description clearly states the tool creates a subscription to a live-data event stream and returns the subscription ID. It uses specific verbs and resources, and the context from sibling tools (list_subscriptions, unsubscribe, recent_alerts) further differentiates its purpose.

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 on when to use this tool vs alternatives, such as the always-on feed accessible via recent_alerts or a direct GET endpoint. It also mentions prerequisites (Pipeworx OAuth account) and phone verification for SMS, though it does not explicitly state 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it returns categorized questions with tool-argument shapes and draws from a live catalog, providing useful context beyond annotations.

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

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

The description is a single paragraph that fronts common query phrases and is information-dense. While slightly verbose with synonym listing, it avoids wasted words and is well-structured for immediate understanding.

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 and one optional parameter, the description fully explains the tool's purpose, return content, invocation options, and use case context. No gaps remain for an agent to misunderstand its role.

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

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

Schema coverage is 100%, and the schema already describes the optional topic parameter with allowed values. The description repeats this information with slight elaboration on focus effect, but adds limited new semantic 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 identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from sibling tools like ask_pipeworx by being a meta-tool for suggestions.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with or without a topic. This provides clear guidance on when to use against 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?

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. Annotations indicate idempotentHint true and destructiveHint false, and the description aligns with these.

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

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

Two sentences with no wasted words. Front-loaded with the core action, then behavioral details.

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

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

For a simple single-parameter tool with annotations, the description covers purpose, behavior, and a usage guideline. No gaps.

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

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

Schema coverage is 100% with a clear parameter description. The tool's description does not add additional semantics beyond the schema, but the context of ownership and deactivation indirectly supports 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 'Cancel a subscription by id' is clear with a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions.

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

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

Specifies ownership enforcement: only own subscriptions can be canceled. While not explicitly listing alternatives, the guideline is clear enough for the agent to understand context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the two pipelines (SEC EDGAR+XBRL for financial, grounded for other), the verdict categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), and the return fields (actual value with pipeworx:// citation and reasoning). 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?

Every sentence earns its place. The description starts with concrete usage examples, then explains the two processing paths, output structure, and efficiency gain. It is information-dense but not verbose, with a clear logical flow.

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 processing pipelines, multiple verdict categories, citation integration) and the absence of an output schema, the description covers all essential aspects: what claims it handles, how it processes them, what it returns, and why it is efficient. No gaps identified.

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 meaning beyond the schema: it explains that tolerance_pct overrides the claim's implied tolerance (capped at 5) and suggests use cases like hallucination detection with 1-2%. This provides practical guidance beyond the schema descriptions.

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

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

The description starts with natural-language examples ('Is it true that…' etc.), explicitly states the purpose is claim verification against authoritative sources, and distinguishes from siblings by explaining it replaces 4-6 sequential calls and handles both financial via SEC EDGAR+XBRL and other claims via grounded pipeline.

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

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

The description clearly states 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates between financial and non-financial claim handling. It does not explicitly list when not to use it or name alternatives, but provides enough context for appropriate usage.

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