Legiscan

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

Annotations already declare read-only and idempotent. Description adds that it probes LLMs, returns per-model results, and requires a key for Anthropic. 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?

Four sentences, front-loaded with main action, then defaults, returns, and use cases. No wasted words.

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

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

Covers all parameters, return format, and use cases. No output schema needed given the description.

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 context: default model is Workers AI, _apiKey is BYO and billed separately. Enhances understanding beyond 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 action (probe), resource (LLMs), and output (visibility score 0-100). Distinguishes from siblings by focusing on AI visibility audits.

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

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

Explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides model selection guidance (default vs. Anthropic w/ key). Could mention when not to use or differentiate from similar sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds behavioral context beyond this: it routes to 5,529 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. It does not contradict annotations, though it omits potential edge cases like rate limits or error 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 longer than typical but front-loaded with the key instruction 'PREFER OVER WEB SEARCH' and organized logically: preference statement, what it does, when to use, examples, and alternatives. Every sentence provides useful guidance, and while it could be slightly more concise, the length is justified given the tool's role as a default entry point.

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

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

The description is comprehensive for a single-parameter tool. It covers use cases, trigger phrases, examples, integration with sibling tools, and return format (structured answer with citation URIs). Despite lacking an output schema, the description fully compensates by explaining what the tool returns and when to use it.

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

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

Schema description coverage is 100% with all six properties documented as aliases for 'question'. The description adds example prompts but no new parameter-specific semantics beyond what the schema already provides. Per the rubric, a score of 3 is appropriate when the schema covers parameters well.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing to relevant tools across 5,529 sources and returns structured answers with citation URIs. It explicitly lists domains (SEC filings, FDA data, FRED/BLS, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by describing when each is appropriate.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions — this is the default entry point.' It also explains when to step up to alternatives ('Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). Trigger phrases like 'what is', 'look up', 'find' are given.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that routing may differ when a candidate is under test, that results are compared against the stable router, and that the last candidate was retired. It also explicitly states 'Falls back to nothing — this IS a full working router', preventing misconceptions about experimental status.

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

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

The description is information-dense with specifics like tool count, candidate status, and retirement date. Every sentence contributes context, and it's structured to lead with the key point (beta version) before elaborating.

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?

Combined with rich annotations and full schema coverage, the description gives the agent everything needed: what it does, current behavior, how to use it, and how it differs from the stable router. The reference to 'same response shape' as ask_pipeworx sufficiently covers return expectations.

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

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

Schema coverage is 100% and all parameters are clearly documented as aliases for 'question'. The description adds no new parameter-level semantics beyond stating 'same arguments', so a baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router that processes natural language questions by routing to the same 5,529 tools. It distinguishes itself from siblings by noting it's the experimental edge with candidate routing improvements, 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?

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and clarifies that no candidate is currently active so it matches the stable router exactly. This gives clear guidance on when to choose this variant over the stable alternative.

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

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

Beyond the readOnly/idempotent annotations, the description discloses refusal behavior with specific reasons (not_in_source, no_tool_match, etc.), evidence verbatim quotes, and an extra LLM call cost. This adds substantial behavioral context not captured by 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 dense but well-structured, moving from purpose to process to return format to usage guidance and cost trade-off. Every sentence earns its place with no wasted words.

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

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

Given the tool's complexity, the description fully covers success and refusal output formats, cost comparison to sibling, and suitable use cases. No output schema is needed because the return contract is explicitly specified.

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 aliases already documented, and the description mentions the tool 'fills arguments' but does not add parameter-level 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 clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb ('extracts') and resource scope. It also distinguishes itself from sibling ask_pipeworx by emphasizing the grounded extraction guarantee.

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 whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups', providing clear when-to-use and when-not-to-use guidance along with an alternative tool.

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

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

The description richly details behavioral traits beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It explains the fan-out process, classifiers, response shapes, resolver contract (including confidence levels and alternatives), parent event extraction, news fallback handling, safety short-circuits, closed market handling, wide-spread liquidity notes, and resolution-rule risk. No contradiction with annotations is present.

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

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

The description is comprehensive but lengthy. It is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), which aids readability. However, it could be more concise by prioritizing the most essential information for agent selection.

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

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

Given the complexity of the tool (3 parameters, no output schema), the description provides exhaustive coverage: purpose, usage, input formats, detailed behavior, return values, edge cases, and safety considerations. It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100%, and the input schema already fully describes the parameters (market, depth, include_raw) with the same information. The description does not add new meaning or constraints beyond what is in the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and includes examples of input types. This distinguishes it from sibling tools like polymarket_arbitrage or 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 explicitly lists usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context, though it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich context: for companies it pulls revenue, net income, cash, debt from SEC EDGAR/XBRL with correct fiscal year handling; for drugs it pulls FAERS, FDA approvals, trial counts. It explains sorting by primary metric and returns paired data with citation URIs.

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

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

The description is front-loaded with example queries and concisely states purpose, data sources, sorting, and efficiency gains. Every sentence is informative, but could be slightly more structured. Still appropriate for the complexity.

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

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

Despite no output schema, the description explains return format (paired data + citation URIs), data sources, sorting, and parameter constraints. It fully covers what an agent needs to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: explains that 'type' determines data source (company vs drug) and that 'values' should be tickers/CIKs for companies or drug names for drugs, with examples. This is beyond the schema's enum and array description.

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

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

The description explicitly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call, with clear examples like 'compare X and Y'. It distinguishes itself from sibling tools by saying 'ALWAYS PREFER over sequential single-pack lookups' and mentions it replaces 8-15 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 strongly advises using this tool for comparing multiple entities over sequential lookups, but does not explicitly mention when not to use it (e.g., for single entity lookups). It provides clear context but lacks explicit exclusions.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description reveals account requirements, depth-specific behaviors (gap recovery, contradictions), citation fetchability guarantees, semantic excerpting, and latency expectations (15-60s, ~90s for thorough). This is substantial context that annotations alone would not provide.

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

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

The description is long but every sentence earns its place. It front-loads the critical account requirement and the alternative tool. Clear structure with concrete examples, quantified facts (1,455 sources, 5,529 tools), and an explicit latency budget all contribute to a dense but well-organized text.

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?

Even without an output schema, the description fully specifies the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), the gaps[]/contradictions[] behavior, and latency. An agent would have all necessary context for selection and invocation.

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

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

Schema coverage is 100% (both parameters have descriptions), but the description adds significant extra meaning: depth's quick/standard/thorough effects are fully explained, and question's 'broad/multi-part is fine — decomposition is the point' plus concrete examples enriches 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 it performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains decomposition into facets routed to 5,529 tools in parallel. It distinguishes itself from open-web search and siblings like ask_pipeworx by detailing the findings packet output.

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?

Gives explicit when-to-use, when-not-to-use, and alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also states 'Best for broad/multi-part questions over structured data'.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it 'returns the 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 provides useful behavioral context beyond annotations, without contradiction.

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

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

The description is moderately sized, front-loaded with the main purpose, then lists example use cases and return details. Every sentence adds value, though it could be slightly more concise. It avoids unnecessary information.

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

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

Given there is no output schema, the description adequately explains what the tool returns (names, descriptions, schemas) and the use context. It covers the key aspects for a discovery tool, including when to use it and the richness of results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the 'query' parameter accepts multiple aliases (q, task, search, description) and provides example values, which helps the agent understand how to use it effectively.

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 provides specific examples of use cases (SEC filings, FDA drugs, etc.) and distinguishes it from sibling tools, which are more specific. The verb 'discover' plus resource 'tools' is precise.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available.' This gives clear when-to-use guidance. It doesn't explicitly mention when not to use it, but the context implies it's for browsing/searching rather than direct calls to known 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 indicate read-only, open-world, idempotent, non-destructive. Description adds specific behaviors: fans out across multiple sources, soft-fails for patents (USPTO sunset), uses fallback chains (GDELT→GNews). 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 comprehensive but slightly verbose. It is front-loaded with examples, but the return fields are listed in a dense paragraph. Could benefit from clearer separation (e.g., bullet points) without losing information.

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

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

For a tool with no output schema and multiple data sources, the description covers all important aspects: input constraints, data sources, return fields, fallback behavior, and limitations (patent sunset). Provides a complete picture for the agent to decide.

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, but the tool description adds critical context: explains that type is limited to 'company', value can be ticker or CIK, and explicitly states that names are not supported. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the verb ('profile'), the resource ('US public company'), and the scope ('full cross-source'). It provides multiple example queries and distinguishes itself from sibling tools like resolve_entity by specifying it requires ticker/CIK, not names.

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 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' Also tells when not to use: if only have a name, use resolve_entity first. Provides clear context and alternative.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds use-case context but does not elaborate on behavioral nuances beyond what annotations state, so it adds moderate 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 two sentences: first states the action, second gives usage guidance. No redundant words; highly 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?

For a simple tool with one parameter, clear annotations, and no output schema, the description covers purpose and usage adequately. It could mention idempotency but annotations already cover it.

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

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

With 100% schema coverage, the parameter 'key' is already documented as 'Memory key to delete.' The description does not add new semantic meaning, so baseline 3 is warranted.

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

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

The description states 'Delete a previously stored memory by key,' which is a specific verb-resource pair. It explicitly pairs with sibling tools 'remember' and 'recall,' distinguishing it as the deletion counterpart.

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

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

The description gives clear when-to-use scenarios: 'context is stale, task is done, or clear sensitive data.' It suggests pairing with remember and recall, but lacks explicit when-not-to-use advice, so a 4 is appropriate.

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

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

Annotations already convey safe, read-only, idempotent behavior. The description adds rich behavioral detail: 'fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format.' It also specifies output as a single text blob. No contradictions.

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

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

The description is compact (two sentences plus a bulleted use-case list). It front-loads the core action and output format. Minor improvement: could list parameters more explicitly, but overall 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 no output schema, the description fully covers the output format ('standard llms.txt markdown format', 'single text blob'). It also explains the process and gives use-case context, making it complete for a simple read-only tool.

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

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

Schema description coverage is 100%, so the description does not need to add parameter details. It merely rephrases the url and max_links purpose without deeper semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to generate a llms.txt file for any URL for AI crawlers. It uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and distinguishes itself from general AI visibility tools by focusing on the llms.txt standard.

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

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

The description explicitly lists three use cases (getting client's site indexed, drafting for own project, auditing competitor). It does not provide when-not-to-use or compare with siblings like 'scan_competitor_ai_presence', but the context is clear enough for an agent to select it appropriately.

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 all true, and destructiveHint false, so the safety profile is clear. The description adds behavioral detail about the return content (status, sponsors, subjects, links) beyond annotations, which is helpful.

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

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

Two sentences plus an example – extremely concise. First sentence states purpose, second gives usage guidance. Front-loaded and no wasted words.

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

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

Given the simple tool (one required param, no output schema), the description covers purpose, input source, example, and return fields. Annotations cover safety. No gaps remain.

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

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

Input schema covers both params with detailed descriptions (bill_id source, API key optional). Schema coverage is 100%. The description repeats the bill_id usage but does not add new semantic meaning 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 'Get the full detail for a single US legislative bill' with specific verb and resource. It lists included fields (status, sponsors, subjects, links) and differentiates from sibling tool search_bills by mentioning using bill_id from search_bills.

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 the bill_id returned by search_bills' which provides clear context for when to use this tool. It includes an example call. While it doesn't mention when not to use or list alternatives, the guidance is straightforward and sufficient.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about output (start/end years, session IDs) and provides an example. This supplements 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 two sentences plus an example, with no unnecessary words. It efficiently conveys purpose, usage context, and a concrete example. Every part earns its place.

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

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

The tool has low complexity with one required parameter and no output schema. The description covers what is returned (start/end years, session IDs). It lacks details like sorting or data limits, but for this simple list tool it 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%, with both parameters (state, _apiKey) described in the schema. The description adds little beyond the schema, only showing an example with state. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists legislative sessions for a US state, including regular and special, with start/end years and session IDs. It uses a specific verb ('List') and resource ('legislative sessions'), and distinguishes itself from sibling tools that handle bills or other entities.

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

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

The description suggests using this tool to 'scope which session to track bills in', providing clear context. It does not explicitly state when not to use or mention alternatives, but the implied use case is adequate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the return fields and the effect of the include_inactive parameter, which is beyond what annotations provide.

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

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

The description is two sentences: the first explains functionality and output, the second gives usage guidance. It is concise, front-loaded, and every sentence earns its place.

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

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

Despite the absence of an output schema, the description lists the return fields. Combined with the rich annotations and single documented parameter, the description provides complete context for the simple list tool.

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

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

Schema description coverage is 100% for the single parameter. The description restates the parameter's purpose but does not add new semantic meaning beyond the schema. However, it provides usage context, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It uses a specific verb-resource pair and distinguishes from siblings like subscribe and unsubscribe.

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

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

The description explicitly advises when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear context and exclusion of 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 annotations are all false and offer minimal safety information, so the description carries the full transparency burden. It discloses operational traits such as rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), the claim_token workflow for follow-up, and the impact on roadmap ('signal directly affects roadmap'). These details go well 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 lengthy but every sentence is purposeful: scope, exclusions, token workflow, rate limits, and roadmap impact all are necessary. It is front-loaded with the core purpose, though the stream-of-thought structure could be more organized. There is no fluff, but a slightly more structured presentation would make it a 5.

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

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

With four optional parameters, no output schema, and sparse annotations, the description compensates fully. It covers the tool's scope boundaries, feedback categories, claim_token usage, rate limits, quota exemption, and operational details like daily digest reviews. This leaves no significant gaps for an agent to misuse the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enriches the schema by explaining the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by advising users to describe issues 'in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' adding meaningful usage nuance to the message and context 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by restricting scope to 'tools served by this Pipeworx connection' and enumerates feedback categories (bug, feature, data_gap, praise), making its purpose unmistakable.

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

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

The description provides explicit when-to-use guidance for each category ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog...') and an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also offers a clear heuristic for identifying Pipeworx tools, leaving no ambiguity about 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, so the tool is safe. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, cached 5min-1h depending on window. This goes beyond the annotations.

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

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

The description is concise, well-structured with bullet points for use cases. Every sentence adds value, and the length is appropriate.

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. It also mentions caching. For a trending tool, this provides sufficient context for the agent.

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

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

Schema description coverage is 100% with well-described enum. The description adds meaning by explaining the trade-off between windows: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

The description clearly states what the tool returns: top tools, top packs, and total call volume over a recent window. The verb 'returns' and resource 'trending' are specific and distinguish it from siblings like 'discover_tools' 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 explicitly lists three use cases (discovering hot data sources, confirming popular tool, aligning use case). It provides clear context for when to use the tool, though it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds extensive behavioral detail: explains monotonicity checks, partition-sum, Jaccard similarity filter, placeholder filtering, and fill check with CLOB depth. No contradiction with annotations.

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

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

The description is verbose but well-structured. Front-loaded with overall purpose, then details each mode and algorithms. Every sentence provides value, though some technical details could be condensed. Still efficient for a complex tool.

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

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

Given no output schema, the description fully explains the response structure (opportunities[], partition_check, fill_check) and edge cases. Covers input, behavior, filtering, and trade advisories. No gaps for a tool of this complexity.

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

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

Schema covers 100% of parameters with descriptions. The description adds significant context: examples of slugs, the checks performed in each mode, and the cross-event behavior. Goes beyond the schema's minimal 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk. The verb 'find' and resource 'arbitrage opportunities' 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?

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Includes a recommendation and warns against trading when edge is non-positive. Mentions alternative tool for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by detailing caching behavior (1h at KV level keyed on all knobs), response structure including diagnostics for empty segments, and the fact that the tool does not mutate state. No contradiction.

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

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

The description is lengthy but well-structured: purpose first, then model families, response shape, configuration knobs, and diagnostics. Every sentence carries distinct information. Could be slightly more compact, but it earns a 4 for organization and efficiency.

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

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

For a tool with 9 parameters, no output schema, and complex response structure, the description is remarkably complete. It explains return segments (by_segment with three groups), diagnostics for debugging empty results, caching policy, and special handling for Fed bets. 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%, so baseline is 3. The description adds substantial value by explaining real-world implications (e.g., slippage context, Polymarket fee structure, why min_kelly and min_partition_leg_kelly behave differently for partition arbs). This extra context warrants 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?

Description starts with a clear verb-resource pair ('Scan top Polymarket markets') and states the core output: opportunities where Pipeworx data disagrees with market price. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by framing this as a daily discovery scan.

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

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

The description explicitly targets the use case 'what should I bet on today' and mentions that agents avoid paging hundreds of markets. It details filters (knobs) but does not explicitly contrast with siblings or state when not to use. Given the clear context, a 4 is appropriate.

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

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

The description discloses behavioral traits beyond annotations, such as snapshot gaps meaning no scan, TTL of 60 days, decay from daily closes (not intraday), and the structure of response. No contradiction with annotations.

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

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

The description is well-structured with front-loaded purpose and detailed output fields. While a bit verbose, each sentence adds value, and there is no redundancy.

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

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

Despite no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and limitations, making it fully actionable for an AI agent.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context like default and max values for days, default window, and explains that snapshots are from polymarket_edges, enhancing understanding.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis.

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

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

The description implies when to use this tool (to assess edge persistence before trading) by contrasting fresh vs. old edges. It also mentions limitations but does not explicitly list alternatives or when not to use.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: it mentions walking the ladder, returning detailed fill data (top_of_book, vwap_fill_price, slippage_pp, etc.), and warning about forced directional risk. 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 lengthy but every sentence serves a purpose, covering both modes and their nuances. It front-loads the core purpose but could benefit from bullet points for the return fields and modes. Given the complexity and the need to explain two modes, it is appropriately sized and 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?

No output schema is provided, so the description must fully explain return values. It does so comprehensively for both modes: lists all returned fields (e.g., top_of_book, verdict, capture_ratio, thin_legs) and explains edge cases (partial fills leading to directional risk). The description is complete given the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining default values (size_usd=1000, side auto for basket), clarifying how size_usd is interpreted differently for single vs basket (max spend vs settlement notional), and noting the automatic side selection based on partition sum. 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between two modes (single-market and basket), using specific verbs like 'check', 'walk the ladder', and 'return' for each. This sets it apart from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why partial fills can convert an arb into an unhedged position, and clarifies the requirement of either `market` or `event` parameter. No exclusion of alternatives is needed as the tool is a prerequisite for specific signals.

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

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

Annotations already mark it read-only, idempotent, etc. The description adds significant behavioral details: compatibility warnings, temporal alignment, skipped cross types, and the note that spreads are mathematically meaningless when temporal alignment is false. No contradictions.

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

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

The description is fairly long but well-structured with clear sections for modes, response, and safety fields. Each sentence adds information; minor redundancy could be trimmed but overall efficient.

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

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

Covers input modes, response structure (leg-by-leg prices, top_spreads_pp), and all safety fields. However, lacks explicit description of the full output JSON layout (e.g., keys like 'matched_pairs', 'skipped_cross_type'). With no output schema, the description should be more detailed about return fields.

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

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

Schema coverage is 100% (all 3 parameters described in schema), but the description adds value by listing the allowed topic values and explaining the override behavior for explicit tickers. Slightly more could be said about parameter interactions.

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, specifies two modes, and explains when spreads are meaningful. It distinguishes from sibling tools like polymarket_arbitrage.

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 describes when to use (equivalent bet shapes), when not to use (compatibility_warning cases), and notes that pre-mapped topics often return warnings. Provides guidance on both predefined and custom pairings.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds listing behavior and scoping. Could mention error handling for missing key, but overall good.

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

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

Two sentences, front-loaded with core action, no redundant information. Efficient and clear.

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

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

For a simple read tool with good annotations, the description covers purpose, usage, scoping, and pairing with siblings. 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 clear param description. Description reinforces and adds the behavior of omitting key to list all keys, providing full context.

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

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

The description clearly states it retrieves a value by key or lists all keys if omitted, with specific verb and resource. It distinguishes from siblings 'remember' and 'forget'.

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

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

Provides explicit when-to-use: 'look up context the agent stored earlier', and scoping details. Does not explicitly say when not to use, but the purpose is clear enough to infer.

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

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

The description discloses that setting mark_read:true modifies event read status, which is a write operation. However, annotations declare readOnlyHint=true, creating a direct contradiction. Per rules, a contradiction scores 1.

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

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

The description is relatively concise (about 150 words) and front-loads the main purpose. It efficiently covers key points, though it could be slightly more streamlined 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?

With 5 optional parameters and no output schema, the description fully explains return fields, filtering options, side effects of mark_read, polling suitability, and an alternative access method. This provides a comprehensive understanding for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical meaning beyond schema, including examples (e.g., type 'sec_8k'), clarifies behavior of mark_read and since, and explains the effect on subsequent calls.

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 'Pull fired events from your subscription feed,' specifying the action (pull) and resource (alerts). It differentiates from sibling tools like list_subscriptions by focusing on retrieving alert data rather than managing 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?

The description includes context such as 'Polls work fine' and mentions an alternative access method (GET endpoint), providing guidance on when to use the tool. However, it lacks explicit exclusions or when-not-to-use instructions compared to siblings.

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

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

Annotations already declare safe read-only, idempotent behavior. The description adds significant behavioral details: fans out to multiple sources in parallel, fallback from GDELT to GNews, soft-fail for USPTO patents, and return structure including citation URIs. 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 relatively long but front-loaded with common use cases. It packs a lot of necessary information into a few sentences. While it could be slightly tighter, it avoids redundancy and each 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?

Given the tool's complexity (multiple data sources, parameter options, fallback behavior) and the absence of an output schema, the description covers all critical aspects: sources, date handling, return format, and alternative tool. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the 'since' parameter accepts both ISO dates and relative shorthand with examples ('7d', '30d', '3m', '1y'), and recommends '30d' or '1m' for typical monitoring. It also clarifies that 'value' can be a ticker or zero-padded CIK.

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 representative queries and states the tool provides a change feed for a company, covering SEC, news, and patents. It explicitly distinguishes itself from the sibling tool entity_profile, which focuses on static profiles. The verb 'change feed' and resource 'company' are specific and 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?

The description provides explicit when-to-use scenarios ('What's new with X', 'latest on Y') and when-not-to-use (use entity_profile instead for static profile). It also gives alternatives and usage context, such as the fallback behavior between GDELT and GNews.

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 idempotentHint=true and destructiveHint=false. Description adds lifecycle details: persistent for authenticated users, 24-hour retention for anonymous, and scoping by identifier. No contradictions.

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

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

Three sentences, front-loaded with purpose, each sentence adds essential information. No wasted words.

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

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

Given 2 params, no output schema, and annotations, the description fully covers when and how to use, scoping, persistence, and pairing with siblings. Complete for a storage tool.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by exemplifying key naming conventions and value type, exceeding the baseline of 3.

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

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

Clearly states the tool saves data for reuse across conversations/sessions, with concrete examples. Distinguishes 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 advises when to use ('discover something worth carrying forward') and pairs with recall/forget, providing clear usage context.

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

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

Despite annotations already declaring read-only and idempotent behavior, the description adds valuable behavioral context: every identifier is labelled with its source, unresolved identifiers are explicitly listed under 'unresolved', and LEI/FIGI enrichment degrades gracefully if upstream services are unavailable. It also discloses internal cascading through multiple endpoints.

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

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

The description is long but front-loaded with purpose and examples, then organized into SUPPORTED TYPES. It contains no filler, and each section adds necessary detail for a tool that cascades across multiple sources. Slightly verbose but appropriate for the complexity.

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

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

Given no output schema, the description thoroughly covers what the tool returns (canonical identifiers, source labels, unresolved list), input variations, graceful degradation, and internal cascade behavior. It even notes citation formats for drug lookups. Nothing critical is missing for an agent to decide when to use it and what to expect.

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

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

Schema coverage is 100%, but the description substantially enhances meaning: it explains what 'company' vs 'drug' resolve to, acceptable input formats (ticker, CIK, name; brand/generic), and the exact identifiers returned (CIK, LEI, FIGI, RxCUI). This goes far beyond the schema's terse parameter descriptions.

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

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

The description clearly states a specific verb ('resolve') and resource (user-spoken NAME to canonical/official identifiers), with examples of user queries. It explicitly frames the tool as the go-to when you have a name but need an ID, distinguishing it from siblings that use IDs for further analysis.

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 a clear directive ('Use FIRST whenever you have a name but need an ID') and explains that it replaces 2-3 manual lookups. It does not explicitly name alternative tools for cases where resolve_entity is not appropriate, but the 'FIRST' guidance gives strong contextual cues.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds specifics: it probes with ai_visibility_check, ranks by score, returns score/confidence/signal density, and treats the first entity as the subject. This provides valuable 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 three concise sentences that front-load the main function, followed by method, use case, and output format. Every sentence earns its place with no wasted words.

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

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

The description adequately covers input, process, and output format, referencing the underlying ai_visibility_check. However, it could be more complete by specifying ordering direction (e.g., descending score) and error handling 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?

Schema coverage is 100%, providing a baseline of 3. The description adds value by specifying that the first entity is treated as the 'subject' for narrative purposes, which is not in the schema description for the entities parameter.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side', identifying the specific verb 'compare' and resource 'AI visibility'. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison), making it distinct.

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 a concrete use case ('competitive AI-marketing audits') and implies when to use this tool over the sibling ai_visibility_check for single entities. However, it lacks explicit '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?

Beyond annotations (readOnly, idempotent), description discloses composite call behavior, partial failure degradation, and bundlephobia's first measurement delay (5-30s). It adds valuable context about sources_failed reporting, which annotations do not cover. 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?

Description is front-loaded with main purpose and use cases, then details return structure, ecosystem limitations, and failure behavior. All sentences are informative, though slightly verbose. Could tighten but structure is logical and effective.

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

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

Despite no output schema, description fully explains return format (summary block, advisories, links, alternatives) and handles complexity like partial failures and performance delays. Adequate for agent to understand tool capabilities and expectations.

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

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

Schema covers both parameters with descriptions (package name, version with default). Description adds minor context (scoped packages accepted, version defaults to latest), but schema coverage is 100%, so baseline of 3 is appropriate. No significant added meaning beyond 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?

Description clearly states the tool is a composite check for npm packages using deps.dev and bundlephobia, specifying the exact resource and action. It implicitly distinguishes from sibling tools by its unique focus on npm dependency analysis, setting it apart from other research 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?

Description explicitly provides when to use ('is X safe / popular / small', 'what does adding lodash cost me') and when not to use ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), offering clear context 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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that it returns matching bills with specific fields, but does not mention any behavioral traits like result limits, pagination, or performance implications. Given the annotations, this is acceptable but could provide more detail.

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 to three sentences, starting with the core purpose, then scope, then return fields, and concludes with an example. Every sentence adds value; there is no redundancy or fluff. It is appropriately front-loaded.

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

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

For a search tool with no output schema, the description covers purpose, scope, return fields, and links to get_bill. It lacks explicit mention of result limits or pagination, but the example and parameter descriptions (in schema) are rich. Overall, it is fairly complete and actionable 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 description coverage is 100%, so the schema already documents all four parameters adequately. The description adds an example that shows usage but does not provide additional meaning beyond what the schema offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: full-text search of US state and federal legislation by topic. It specifies the scope (one state or nationwide) and what is returned (bill number, title, state, last action, ID). This distinguishes it from sibling tools like get_bill, which retrieves a specific bill by ID.

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: 'to find out what bills are about a given topic.' It mentions that the resulting bill_id can be passed to get_bill, implying get_bill for retrieval. It does not explicitly state when not to use or list alternatives, but the context is clear enough for an agent to decide.

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

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

The description adds significant behavioral context beyond what annotations provide: it specifies the embedding model (BGE-base-en), similarity metric (cosine over 500-char overlapping windows), character cap (200K chars with truncation and flagging), and output details (offsets and similarity scores). This fully informs the agent of the tool's internal 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 concise, structured with a clear opening statement, use case, pairing advice, and technical details. Every sentence adds value without redundancy. It is front-loaded with the primary purpose.

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

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

Despite the absence of an output schema, the description fully explains the return format (passages with character offsets and similarity scores). It also covers edge cases (truncation), technical details (embedding model, window size), and integration with sibling tools, making it complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The tool description adds value by providing example queries for the 'query' parameter and clarifying the character cap for 'text'. The 'limit' parameter defaults are also given. This extra context merits a score above the baseline of 3.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifies the input (text and query), and the output (top-N passages with offsets and scores). It distinguishes itself from siblings by explicitly mentioning its pairing with ask_pipeworx_grounded for grounding over relevant passages.

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: 'Use when the record is too big to cram into the prompt.' It also explains the benefit (saves context, returns only relevant passages) and mentions the character cap and truncation behavior, providing clear guidance on its appropriate use.

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

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

The description adds significant behavioral context beyond annotations: it notes the requirement for a persistent account, mentions SMS rate limits, webhook auto-disable after failures, and that the webhook secret is returned only once. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

The description is well-organized into logical sections (type, params, delivery) and includes examples. Every sentence adds value, though it is slightly verbose. It could be tightened 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 subscription types, nested delivery options, multiple required fields), the description covers all key aspects: requirements, constraints, examples, and side effects. No output schema exists, but the description explains return values (subscription id, webhook secret).

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

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

Although schema coverage is 100%, the description adds rich detail for each type parameter (e.g., sec_8k items codes, fred_series series_id) and delivery options (SMS verification, webhook HMAC signing). This provides crucial usage guidance beyond the schema.

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

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

The description clearly states the action ('creates a proactive monitoring subscription') and the resource ('live-data event stream'). It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying creation and subscription types.

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

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

The description provides explicit prerequisites (Pipeworx OAuth account, not for anonymous/BYO) and explains when to use specific subscription types with examples. It lacks explicit when-not-to-use guidance but strongly implies appropriate contexts.

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 safe, read-only, idempotent behavior. Description further explains it returns category-bucketed example questions with exact tool+argument shapes, using the live catalog. 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?

Description is relatively long but well-structured, front-loaded with the canonical question, and uses bullet-point-like examples. Slightly verbose but justified by the informational density.

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

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

Though no output schema, description thoroughly explains the return format (category-bucketed example questions). Parameter is fully covered. Adequate for a discovery tool with no nested objects.

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

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

Schema coverage is 100%. Description adds meaning by listing exact topic values and explaining the effect of omitting vs specifying a topic, which goes beyond the schema.

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

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

Description explicitly states the tool is the onboarding entry point for a new agent, returns category-bucketed example questions, and distinguishes from siblings by focusing on 'what can I ask?' rather than executing queries.

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?

Clear guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to pass the optional topic parameter.

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

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

Beyond annotations (destructiveHint=false), the description explains that the row is deactivated not deleted, and historical events remain available via recent_alerts. This adds valuable 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?

Three short sentences convey all necessary information without redundancy. Every sentence adds value and the key action 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 simplicity (single parameter, no output schema), the description is complete. It covers purpose, ownership, behavior, and side effects, leaving no unanswered questions for an AI agent.

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

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

The input schema covers the single parameter 'id' with a description. The tool description does not add further details about the parameter beyond what the schema provides, so it meets the baseline for 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 begins with 'Cancel a subscription by id', clearly stating the verb and resource. It further distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement.

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 ownership enforcement, which guides when to use this tool (only for own subscriptions). It does not explicitly mention alternatives, but the context is clear. A slight improvement could be adding a note about when not to use it.

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

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

The description adds rich behavioral context beyond the annotations: it explains that could_not_verify means the check did not happen and must not be treated as evidence, clarifies unsupported means no source covers it, and discloses routing logic (SEC EDGAR vs grounded pipeline). This is significant operational detail that annotations do not provide.

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

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

The description is long but well-structured, moving from trigger phrases to purpose, routing, return values, and critical caveats. Every sentence carries useful information, though the opening list of examples is slightly verbose. The caveats about could_not_verify and unsupported are essential and not redundant.

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

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

With no output schema, the description fully explains return values (verdict list, actual value with citation, reasoning) and error semantics (verification_error with stage and detail). It covers routing, usage, failure modes, and the fact it replaces multiple sequential calls. For a tool with two simple parameters, this is comprehensively complete.

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

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

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds extra meaning: tolerance_pct can be set to 1–2 for hallucination detection, default is implied by wording capped at 5, and the claim parameter's routing behavior is clarified. This elevates it above baseline.

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

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

The description opens with a list of natural-language triggers like 'fact check' and 'verify the claim that…', then states 'natural-language claim verification against authoritative sources' with a clear verb and resource. It distinguishes from siblings by focusing on verification with a verdict, which is a unique purpose among the listed tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides routing details for different claim types. It does not name alternative tools or explicit exclusion cases, but the context is clear enough to guide selection.

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