Data Sf

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

Disclosures additive beyond annotations: default model is free, Anthropic usage is BYO key with direct payment to Anthropic, and return structure includes per-model and combined views. No contradictions with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

Concise, front-loaded with main action, no redundant sentences. Every sentence earns its place, providing essential info without fluff.

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

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

Given no output schema, description fully covers return structure, use cases, parameter nuances, and behavioral specifics. Complete enough for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. Description reinforces parameter meanings (e.g., 'context' helps disambiguate) but adds only modest extra value beyond schema (e.g., stating default model is free).

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 it probes LLMs for entity knowledge and scores visibility (0-100) per model, with specific verb 'probe' and resource 'LLMs'. Distinguishes from siblings like scan_competitor_ai_presence by focusing on multi-model scoring.

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

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

Provides clear context: useful for AI-marketing audits, pre-launch checks, competitive monitoring. Specifies default model and conditions for using Anthropic (requires _apiKey). Lacks explicit alternatives or when-not-to-use, but use cases are well-defined.

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

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

Annotations already establish it as read-only, open-world, idempotent, and non-destructive. The description adds substantive behavioral context: it routes to 5,462 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and is one fast call. This goes beyond the annotations and gives the agent a clear mental model of how the tool operates.

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: it leads with the most important directive ('PREFER OVER WEB SEARCH'), then explains the mechanism, gives examples, and ends with alternative tool guidance. Every sentence adds value, though it could be tightened slightly. The front-loading is 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?

For a complex routing tool with no output schema, the description adequately explains the return format (structured answer with citation URIs) and provides concrete examples. It covers usage scenarios and alternatives, making it sufficiently complete for an agent to invoke correctly. Minor gaps like exact response structure are acceptable given the tool's breadth.

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

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

Schema description coverage is 100% and the schema already documents the 'question' parameter and its six aliases. The description provides helpful examples and clarifies the type of queries to ask, but it does not add significant detail beyond what the schema already specifies. This meets the baseline for full schema coverage.

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

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

The description clearly states the tool's function: it routes questions to the appropriate tool among thousands, fills arguments, and returns structured answers with citation URIs. It also explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique role clear.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It names specific alternatives for different scenarios (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions) and even clarifies that breaking-news is already covered. This is exemplary usage guidance.

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

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

The description discloses that it is a live experimental edge with candidate routing improvements that may be enabled, that no candidate is currently active, and that it is a full working router with no fallback. This adds meaningful context beyond the annotations without contradicting them.

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

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

Three sentences pack definition, current state, usage instruction, and clarification with zero filler. The description is front-loaded with 'Beta version of ask_pipeworx' 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?

The description covers purpose, current behavior, usage, and relationship to the stable router, and mentions 'same response shape' for output expectations. It does not elaborate on question scope or error behavior, but those are not essential for a universal router with rich annotations and 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% with all six parameters described as aliases for 'question,' and the description only references 'same arguments' without adding new meaning. The baseline of 3 applies because the schema carries the parameter semantics fully.

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 identifies the tool as a beta universal router with identical tools and arguments as ask_pipeworx, distinguishing it from the stable sibling by its experimental routing. The verb 'ask' plus resource 'pipeworx beta' is specific and unambiguous.

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

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

Explicit guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' This gives a clear condition for when to choose this tool over the stable alternative, though it does not explicitly mention when not to use it or name other alternatives beyond 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?

Goes far beyond annotations by detailing the refusal mechanism with specific refusal_reason values, the return object structure including evidence verbatim quote, and the behavioral constraint of using ONLY tool result content. Annotations already declare read-only/idempotent, and the description adds crucial context about refusal behavior and output guarantees, with no contradictions.

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

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

Description is information-dense yet well-structured: first sentence states purpose, second explains process and return/refusal formats, third gives usage guidance and cost. Every sentence contributes value, and key information is front-loaded. No filler or redundancy.

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

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

Given the tool's complexity and lack of output schema, the description fully compensates by detailing success/refusal response shapes, error categories, and operational cost. It also situates the tool against siblings and provides concrete use cases (financial, legal, medical), making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with the question parameter and all aliases documented. The description does not add parameter-specific semantics, but it does mention 'fills arguments' which implicitly refers to the question parameter. Since the schema fully describes the parameter, baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains its mechanism: routing, fetching data, and extracting answers strictly from tool results. It distinguishes itself from sibling ask_pipeworx by emphasizing groundedness and explicit refusals, leaving no ambiguity about its purpose.

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

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

Provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' It also names the alternative (ask_pipeworx) and explains the cost tradeoff (one extra LLM call), giving clear when-to-use and when-not-to-use context.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds extensive behavioral details: fan-out logic, resolver contract with confidence levels, parent_event extraction, news fallback handling, safety short-circuits, and resolution-rule risk analysis. No contradictions with annotations.

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

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

The description is very long and dense, but it is well-structured with clear section headers (e.g., RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR). While it contains valuable information, its length may hinder quick parsing by an AI agent. Some redundancy exists; for example, the fan-out examples could be summarized more concisely.

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

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

Given the tool's complexity (3 parameters, complex fan-out, resolver, parent_event, news handling, cancellation rules), the description covers all necessary behavioral aspects comprehensively. There is no output schema, but the description details the response shapes sufficiently, including market, analysis, evidence, and all subfields.

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

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

All three parameters are fully described in the input schema (100% coverage). The description adds valuable context beyond the schema: it explains that market accepts slug, URL, or question text; it clarifies default values for depth and include_raw; and it gives usage examples. However, the baseline is 3 due to high schema coverage, so 4 is appropriate for the added 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 the tool researches Polymarket bets by pulling Pipeworx data in one call. It specifies the resource (Polymarket bet) and verb (research), and provides concrete use cases like 'should I bet on X' which 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 says when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also provides implicit guidance by describing various classifiers and examples, helping the agent decide when this tool is appropriate.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are all consistent. The description adds behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is relatively long but front-loaded with example queries. While informative, some redundancy could be trimmed (e.g., 'side-by-side comparison' and 'head to head'). Still, it is well-structured and readable.

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

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

Given the tool's complexity (two entity types, multiple data sources), the description covers use cases, sorting, and return format (paired data + URIs). No output schema, but description adequately sets 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% with descriptions for both parameters. The description adds meaning: explains enum values (company/drug) with specific data sources, and provides example inputs for values (tickers/CIIKs or drug names). This goes beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with example queries like 'compare X and Y' and 'which is bigger'. It distinguishes from sequential single-pack lookups, making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', guiding when to use. It does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints, but the description adds substantial behavioral context: auth prerequisites, paid tier gate, explicit gaps[] instead of invented answers, fetchable citation_uri guarantee, semantic excerpting, contradictions[], and latency expectations. 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 long but every sentence earns its place, covering prerequisites, purpose, alternatives, depth semantics, output guarantees, and performance expectations. It is front-loaded with account requirements and the primary alternative, then flows logically through behavior details.

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

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

Despite having no output schema, the description fully explains the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri), gap/contradiction handling, and time expectations. For a complex tool with only two parameters, this is exceptionally complete.

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

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

Schema coverage is 100%, yet the description adds crucial parameter semantics beyond the schema: depth:'thorough' requires a paid plan, depth:'standard' performs gap recovery, and question is explicitly suited for broad/multi-part phrasing. This materially helps the agent choose correct values.

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 grounded multi-source research across 1,419 structured data sources in one call, decomposing questions into facets and routing to 5,462 tools in parallel. It distinguishes from siblings by explicitly recommending ask_pipeworx for single lookups and current news topics.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, with clear alternatives for single lookups (ask_pipeworx) and breaking/current-news topics (ask_pipeworx). Also specifies account requirements and which depths require payment.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool '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 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 front-loaded with the core purpose and effectively structured with examples and benefits. However, the long list of example domains (SEC filings, financials, etc.) is somewhat verbose and could be more concise.

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

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

Despite lacking an output schema, the description fully compensates by explaining that the output includes 'names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly.' For a discovery tool, this provides complete context 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 description coverage is 100%, with all parameters described. The description adds value by explaining query aliases and providing natural language query examples (e.g., 'analyze housing market trends'). However, it does not add significant semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It lists numerous example domains (SEC filings, financials, etc.) and explains that it returns top-N relevant tools with full schemas. It distinguishes from siblings by advising to 'Call this FIRST when you have many tools available and want to see the option set.'

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 to call this tool 'FIRST when you have many tools available and want to see the option set (not just one answer).' It provides clear context for when to use it. However, it does not explicitly state when not to use it (e.g., if you already know the exact tool name).

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, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: it fans out across multiple sources, explains the patents sunset soft-fail, details return fields, and clarifies parameter requirements. 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 densely packed with necessary information. It front-loads example queries. Every sentence serves a purpose, though some restructuring could improve readability.

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

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

Given the tool's complexity (multiple data sources, uncertain availability of patents, no output schema), the description is remarkably complete: it lists all return fields, data sources, and even warns about the patents sunset. No gaps for an agent to infer.

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 important meaning beyond schema: 'type' only supports 'company', 'value' expects ticker or zero-padded CIK, explicitly states names not supported. This goes beyond the schema's enum and description.

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

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

The description clearly states it provides a full cross-source profile of a US public company, listing specific data sources (SEC EDGAR, XBRL, USPTO, GDELT, GLEIF) and return fields. It distinguishes from sibling tools like resolve_entity by noting that names are not supported and should be resolved first.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells when not to use (if only have a name, use resolve_entity first) and provides example queries.

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 confirms the destructive nature ('Delete'), which aligns with the annotation 'destructiveHint: true'. It adds context that it operates on 'memory' by 'key', but does not reveal side effects or error behavior. Since annotations already cover safety profile (destructive, idempotent), the description 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 three sentences, front-loaded with the purpose, followed by usage context and sibling pairing. No extraneous information; every sentence serves a 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?

The tool is simple (1 param, no output schema). The description covers purpose, usage, and tool relationships. Missing detail on behavior for non-existent keys, but the idempotent hint implies no error. Overall complete enough for effective use.

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

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

The input schema already fully describes the 'key' parameter (100% coverage). The description merely echoes 'by key' without adding new semantic details such as format, constraints, or examples beyond the schema's own example. 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 action ('Delete a previously stored memory by key') and specifies the resource and operation. It distinguishes itself from siblings by explicitly naming 'remember' and 'recall' as complementary tools.

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

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

The description provides explicit usage scenarios ('when context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with siblings. It lacks explicit when-not-to-use or alternative recommendations, but for a simple tool it's sufficient.

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

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

The description complements the annotations (readOnlyHint, idempotentHint) by explaining the tool's behavior: it fetches the page, extracts data, and emits a text blob. This adds context beyond the annotations, though it could further detail that no modifications are made to the target site.

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

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

The description is concise (two sentences) and front-loaded with the primary action. It avoids unnecessary words but could be slightly more structured (e.g., separate output format mention). Still, every sentence contributes value.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description fully covers what the agent needs to know: input, process, output format, and use cases. No gaps remain for effective invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description does not add significantly to the parameter semantics beyond what the input schema provides (URL and max_links with defaults). No additional constraints or usage tips are given.

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

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

The description uses a specific verb-resource pair ('generate a production-ready llms.txt file') and clearly states the tool's function: fetching a page, extracting title/description/key links, and emitting standard format. It distinguishes from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description lists concrete use cases (getting a client's site indexed, drafting llms.txt, auditing a competitor) and implicitly indicates when to use this tool over others. However, it does not explicitly state when NOT to use it or mention alternative tools, which would have made it a 5.

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

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

Description aligns with annotations (readOnly, idempotent). Adds context that default returns only active subscriptions and mentions optional include_inactive parameter. No contradiction.

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

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

Two sentences, no wasted words. First covers purpose and output, second adds usage context. 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 listing tool with one optional parameter, description covers purpose, output, and use case. No output schema but fields are listed. Minor omission: does not explicitly state that only caller's subscriptions are returned, but 'caller's' is present.

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 description of include_inactive. Description complements by implying default behavior (active only), but adds minimal new parameter meaning.

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

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

Clearly states the verb 'list', resource 'subscriptions', and explicitly lists the returned fields. 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?

Provides explicit guidance: use to review active subscriptions before adding more or to obtain an id for cancellation. Helps decide when to use this tool.

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

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

Annotations only provide hints (readOnlyHint=false, etc.), leaving the description to explain behavior. It discloses rate limits ('5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), the claim_token flow for async status, and instructs not to paste end-user prompts. 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 long but front-loads the purpose and usage, followed by operational details. A few sentences (e.g., 'The team reads digests daily and signal directly affects roadmap') are motivational rather than essential, keeping it from a perfect score.

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

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

With no output schema, the description explains the claim_token return and how to use it later to read status, while also covering rate limits and scope exclusions. For a feedback tool with four optional parameters, this is complete and actionable.

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

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

Input schema covers all 4 parameters with rich descriptions, setting baseline at 3. The description adds syntax for claim_token ('pipeworx_feedback({claim_token:"pwfb_…"})') and message guidance ('don't paste the end-user's prompt'), raising its value 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?

The description clearly identifies the action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and names the resource (Pipeworx feedback). It distinguishes from sibling ask_pipeworx tools by specifying this is for reporting tool issues, not asking questions.

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

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

Explicitly lists trigger conditions ('Use when a tool returns wrong/stale data...') and exclusions ('ONLY for tools served by this Pipeworx connection...'). It also tells agents to file with a different server if the tool isn't Pipeworx's, providing clear alternative routing.

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. Description adds value by explaining data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). 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, each earning its place. Front-loaded with purpose, then use cases, then behavioral details. No fluff.

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

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

For a simple tool with one optional parameter and no output schema, description fully explains inputs, outputs, and use cases. 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 covers 100% of parameters with enum and description. Description adds meaningful context: shorter windows for hot trends, longer for steady-state. Schema already does most of the work.

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

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

Clearly states it returns top tools, top packs, and total call volume over a recent window. Distinguishes itself from sibling tools like 'discover_tools' by focusing on trending usage.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. Provides clear context without excluding alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: algorithm specifics (monotonicity violations, partition-sum checks), thresholds (≥0.30 Jaccard, >3pp deviation, >20% placeholder fraction), fill check against live CLOB depth, and output structure. No contradictions.

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

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

The description is front-loaded with purpose and modes, then covers internal details like SEMANTIC ANCHOR and PARTITION FILTER. While every sentence adds value, some algorithmic minutiae could be condensed for an agent audience. It is well-structured but slightly verbose.

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

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

Given no output schema, the description comprehensively covers input behaviors (no args, event, topic), output fields (opportunities[], gap_pp, suggested_trade, etc.), and internal filtering (placeholder fraction, similarity threshold, fill check). It addresses edge cases and directs to sibling for custom sizing, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds rich semantics: explains how 'event' triggers single-event mode with partition check and date-axis/threshold-axis ordering, and how 'topic' triggers cross-event scanning with Jaccard similarity filtering. This goes well beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: default trending scan, single-event (event), and cross-event (topic). Mention of 'For custom sizing use polymarket_fill_risk' hints at differentiation from sibling tools, making purpose and scope very 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?

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also provides when-not: 'do not trade it' if realizable_edge_pp ≤ 0, and directs to sibling polymarket_fill_risk 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 readOnly, idempotent, non-destructive. The description adds valuable behavioral context: caching (1h KV-level), edge calculation net of slippage, diagnostic output for empty segments, and 24h-move warnings. It also explains that fed_candidates are excluded from ranking. This goes beyond annotations without contradicting them, earning a high score.

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 verbose, spanning multiple paragraphs. It is front-loaded with the main purpose, which is good, but the detailed breakdown of model families and internal logic could be summarized for brevity. While organized, it is not maximally concise for its complexity level.

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

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

Given the absence of an output schema, the description provides extensive detail on response structure (by_segment, fed_candidates, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, etc.). It also explains diagnostics for empty segments and knob interactions. This covers most contextual needs for an agent 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?

All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra context beyond the schema, such as explaining the interaction between min_kelly and min_partition_leg_kelly, the meaning of tradeable-edge filters, and default values. This enhances understanding, justifying a score of 4.

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

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

The description clearly states the tool's purpose: to scan Polymarket markets and return opportunities where Pipeworx data disagrees with market price. It uses specific verbs and resources ('scan top Polymarket markets', 'return opportunities'). While it distinguishes from the generic 'paging hundreds of markets' approach, it does not explicitly differentiate from sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker', which slightly reduces clarity.

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 guidance on when to use the tool ('what should I bet on today'), explains the three segments and their conditions (e.g., 'concentrated_longshot is rare-by-design'), and gives rationale for filtering (e.g., fed_candidates excluded due to data limitations). However, it lacks explicit contrasts with sibling tools or when NOT to use this tool, leaving some ambiguity about optimal selection among alternatives.

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

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

The description extensively covers behavioral traits: explains response structure (tracked, expired, snapshot_dates), data freshness limits (60-day TTL, cache-miss dependency), and that decay is based on daily closes, not intraday. This adds significant value 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 moderately long but well-structured, with clear sections for response fields and limitations. Every sentence provides useful information, though it could be slightly more concise without losing clarity.

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

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

Given the tool has only two parameters and no output schema, the description is complete: it explains response fields, data sources, and limitations. The annotations confirm safety, so no missing information.

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

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

Schema coverage is 100%, so the description adds only minor value: confirms defaults (14 days, '1wk') and mentions max 30 days (while schema says clamp 2-30). This is adequate but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge age and trend. It distinguishes from sibling polymarket_edges by focusing on history rather than current edges.

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

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

The description gives explicit context for when to use: to differentiate between fresh and old edges. It implies usage for historical analysis, but does not explicitly state when not to use or name alternatives beyond polymarket_edges.

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 comprehensive annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds rich behavioral details: walks the order book ladder, returns top-of-book, VWAP fill price, slippage, share fill info, verdicts, per-leg details, thin leg identification, and forced directional risk warnings. No contradictions with annotations.

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

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

The description is lengthy but well-structured: starts with a concise one-liner, then uses bold section headers to distinguish modes and usage guidelines. While some redundancy exists (e.g., repeating parameter defaults), the organization aids comprehension 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 4 parameters, two modes, and no output schema, the description thoroughly covers return values for both modes, including edge cases like thin_legs, forced_directional_risk, and profit calculations. It provides complete guidance for an AI agent to understand inputs, outputs, and risks.

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%, providing baselines for each parameter. The description adds significant value by explaining parameter interactions (market vs event exclusivity, side default logic, size_usd interpretation per mode, clamping range) that go beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explains two distinct modes (single-market and basket/partition) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it.

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

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

Explicitly instructs: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also provides rationale about thin books and partial fills converting arb into directional positions, offering clear context for when to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: it explains the spread calculation, safety fields (compatibility_warning, temporal_alignment, skipped counters), and limitations (e.g., 'Real cross-venue spreads are rarer...'). This goes well 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 well-structured: it front-loads the core purpose, then explains modes, response fields, and safety fields. While comprehensive, it is slightly verbose (e.g., detailed explanation of compatibility warning conditions). Every sentence adds value, but minor trimming could improve conciseness 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?

No output schema is provided, so the description must fully explain the response. It describes the spread, leg-by-leg prices, top_spread_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers edge cases (e.g., bet shape mismatch, temporal misalignment). The description is complete given the tool's complexity and lack of output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description elaborates on the parameters by explaining the two modes: topic provides pre-mapped shortcuts (listing all 10), while kalshi_event_ticker/polymarket_event_slug allow custom pairings. It also notes that explicit fields override the topic-mapped side. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (compute/show), resource (spread between venues), and scope (same resolving question). It clearly distinguishes from sibling tools by focusing on a niche cross-venue comparison.

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

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

The description outlines two usage modes (topic shortcuts and explicit tickers) and explains when each is appropriate. It warns that most pre-mapped topics return compatibility warnings, setting expectations. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or provide 'when not to use' guidance, which would elevate it.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds value by noting scoping to user identifier and the ability to list all keys. 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 three concise sentences with front-loaded action. Every sentence adds unique value without redundancy.

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

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

Given the simple tool with one optional param, no output schema, and rich annotations, the description fully covers usage, scoping, and pairing with siblings.

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 param description is clear. The description enhances understanding by explaining that omitting key lists all saved keys.

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 'Retrieve a value previously saved via remember, or list all saved keys', providing a specific verb and resource. It distinguishes from sibling tools '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?

It clearly explains when to use ('to look up context the agent stored earlier') and provides alternatives ('Pair with remember to save, forget to delete'). This guides appropriate tool selection.

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

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

Annotations declare readOnlyHint=true, implying no state changes, but the description explicitly states that setting mark_read:true flags returned events read, which modifies state. This is a direct contradiction. Beyond this, the description adds context about the feed endpoint and polling but fails to resolve the inconsistency.

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 well-structured sentences: first sentence defines purpose and output, second explains parameters, third provides polling guidance and alternative endpoint. No superfluous 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 no output schema, the description sufficiently explains return fields. It covers all parameters with additional context. It mentions the alternative REST endpoint for scripts and dashboards. Minor omission: no error handling or rate limit info, but overall complete for a read 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%, providing baseline 3. The description adds context: explains that type filters by subscription type, since filters by fired_at, mark_read flags events read, unread_only filters unread, and limit reduces count. It also mentions return fields (source, citation_uri, raw payload). This exceeds 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?

Description clearly states verb 'Pull' and resource 'fired events from your subscription feed', includes return fields and filtering options, distinguishing it from sibling tools like list_subscriptions or subscribe.

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 explains filtering by type and since, mark_read behavior, and that polling works fine. It mentions an alternative endpoint for scripts. However, it does not explicitly state when not to use this tool or suggest alternatives among the numerous 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 indicate readOnly, openWorld, idempotent; description adds parallel fan-out, source fallback behavior (GDELT→GNews), soft-fail for USPTO, and return structure details.

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

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

Concise and front-loaded with example phrases; every sentence is informative. Slightly dense but 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?

Despite no output schema, description explains the result structure and covers all sources, fallback, and parameter behavior thoroughly for a complex tool.

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

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

Schema covers all parameters; description adds context for `type` (only company), `since` formats including relative shorthand, and `value` accepting ticker or 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 clearly states the tool returns a change feed for a company in a time window, listing specific sources and distinguishing from the sibling entity_profile tool.

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 example queries, guidance on the `since` parameter (e.g., use '30d' for monitoring), and a clear alternative tool (entity_profile) for static profiles.

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

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

Discloses scoping by identifier, persistence differences between authenticated and anonymous users (24hrs vs persistent), and pairing with recall/forget. This goes beyond annotations which only indicate idempotent and non-destructive.

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

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

Four sentences, each serving a distinct purpose: purpose, usage example, storage details, companion tools. No redundancy, front-loaded with key action.

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 store tool without output schema, the description covers all relevant aspects: what it stores, scoping, persistence, and how to retrieve/delete. Complete for the task.

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 examples in descriptions. The tool description reiterates key-value pairing but adds no new semantic detail beyond what schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse, with examples like resolved ticker, target address, etc. It distinguishes itself from siblings by mentioning recall and forget as companion 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?

Explicitly says 'Use when you discover something worth carrying forward' and gives concrete examples. References companion tools for retrieval and deletion, providing clear when-to-use and when-not-to-use guidance.

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

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

Beyond the read-only and non-destructive annotations, the description discloses internal cascading behavior, external data sources (SEC EDGAR, RxNorm), citation URIs, and auto-disambiguation. It also details the exact return fields for each entity type, adding significant behavior context not available from annotations alone.

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

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

The description is dense but well-organized: it opens with example queries, states the core purpose, gives a usage directive, then breaks down supported types with clear formatting. Every sentence adds value without redundancy, making it appropriately sized for the tool's complexity.

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

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

Since there is no output schema, the description fully explains return values for both entity types, including citation URIs and data sources. It also covers input formats and disambiguation behavior, covering the essential context for correct invocation. The tool is relatively simple, and the description addresses all key aspects.

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

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

The schema already documents both parameters with 100% coverage, including accepted formats for value. The description reinforces this and adds meaning by linking the type parameter to specific return structures and noting auto-disambiguation, going slightly beyond the schema's basic definitions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers required by other tools, with specific examples like ticker, CIK, and RxCUI. It explicitly enumerates supported types (company, drug) and what each returns, distinguishing it from sibling tools by positioning it as the first-step lookup when an ID is needed.

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 an explicit trigger condition: "Use FIRST whenever you have a name but need an ID." This gives clear contextual guidance, though it does not explicitly state when not to use the tool or name alternative tools, so it falls short of a 5.

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

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

The description goes beyond annotations (readOnlyHint, idempotentHint, etc.) by explaining the internal process: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized. Details return structure (ranked list, score, confidence, signal density). No contradictions.

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

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

Two sentences with no wasted words. First sentence states action and outcome; second provides usage context and return details. Front-loaded and efficient.

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

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

Given no output schema, the description adequately explains the return format and how the tool works. It covers purpose, parameters, and output, making the tool self-contained.

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 noting the first entity is treated as 'subject' for narrative. This clarifies parameter intent beyond the schema's generic 'entities' 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 starts with 'Compare AI visibility across multiple entities side-by-side', which uses a specific verb (compare) and resource (AI visibility). It clearly distinguishes from the sibling ai_visibility_check by emphasizing multi-entity comparison.

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

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

The description includes a concrete use case ('competitive AI-marketing audits') and an example question. It implicitly guides away from single-entity use (suggesting ai_visibility_check), but lacks explicit when-not statements.

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

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

Discloses that it fans out across two services, returns a summary block with specific fields, handles partial failures gracefully (sources_failed list), and notes that first measurement on new version can take 5-30s. Annotations already provide readOnly/idempotent hints, and description adds practical behavior details 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 a single, dense paragraph that front-loads the main purpose. Every sentence adds value, but it could be slightly more structured (e.g., bullet points). Still very efficient and readable.

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

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

Given the absence of an output schema, the description thoroughly explains the return format (summary block fields, per-advisory detail, links, alternative versions). It also covers ecosystem limitations and partial failure behavior, making it complete for this tool's complexity.

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

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

Schema description coverage is 100% (both parameters have descriptions). The tool description does not add meaningful information beyond the schema; it restates that package is an npm name and version defaults to latest. Per guidelines, baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for adding npm packages, combining deps.dev and bundlephobia data. It distinguishes from siblings as the only dependency scanner, identifies the resource (npm package), and lists specific checks (license, advisories, bundle size, etc.).

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

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

Explicitly states when to use: when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies when not to use (other ecosystems) and suggests alternative (deps.dev:version directly). Provides context on partial failures and behavior.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' This provides transparency about the inner workings and limits.

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, front-loaded with the core action, and each sentence adds essential information. No unnecessary fluff.

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

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

Given the rich schema and annotations, the description covers purpose, usage, behavioral details, and pairing. It is complete enough for an AI agent to decide when and how to use the tool, despite no 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 description largely repeats schema descriptions. However, it adds examples for the query parameter (e.g., 'supply-chain risk'), adding value beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' specifying the verb and resource. It distinguishes itself from sibling tools by explaining when to use it (when the record is too large for the prompt) and pairing with ask_pipeworx_grounded.

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

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

Explicit usage guidelines: 'Use when the record is too big to cram into the prompt — search_within saves context…' and mentions pairing with ask_pipeworx_grounded. No alternative tools are listed, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds limited behavioral context: it notes that _apiKey is optional and affects rate limits, and it describes the return values. No output schema exists, so the description partially compensates, but more detail on pagination or authentication would improve transparency.

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

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

The description is two sentences, front-loaded with the tool's purpose, and contains no filler. Every word serves a purpose, making it highly concise and easily scannable by an AI agent.

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

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

Given that there is no output schema, the description effectively conveys what the tool returns (dataset names, descriptions, and resource IDs) and how to use the results (with sf_query). Annotations cover safety and idempotency, so the description is complete for this search tool's requirements.

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

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

Schema coverage is 100%, so the schema already describes all four parameters. The description adds marginal value by explaining '_apiKey' as optional for higher rate limits and 'query' as keywords, but these are mostly redundant with the schema descriptions. Baseline of 3 is appropriate.

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

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

The description clearly states the tool searches the San Francisco open-data catalogue by keyword and returns dataset names, descriptions, and resource IDs. It distinguishes itself from sibling tools like sf_query (which queries a specific dataset) and sf_recent, making its purpose specific and 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 clear context for when to use the tool (searching for datasets by keyword) and explicitly mentions the returned IDs can be used with sf_query, guiding the agent on downstream usage. It does not explicitly state when not to use it, but the sibling tools offer 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 and idempotentHint. Description adds value by mentioning rate limits and option of app token for higher limits, and implies no destructive 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?

Two concise sentences front-loading the core purpose and usage, with no wasted words. Examples in schema provide further 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?

Covers how to find resource IDs, SoQL capabilities, and authentication. No output schema, but description adequately sets expectations for a query tool. Slight gap on return format.

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

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

Schema has 100% description coverage with clear explanations. Description adds context about SoQL clauses but does not significantly enhance parameter meaning beyond the schema.

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

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

Clearly states it runs raw SoQL queries against San Francisco open-data using a Socrata ID. Distinct from sibling tools like sf_datasets (finds IDs) and sf_recent (common datasets).

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 using sf_datasets to find resource IDs and sf_recent for common ones, guiding when to use alternatives. Could include when not to use, but sufficient for context.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral details: returns latest rows sorted newest-first, supports SoQL where filters. This is consistent and provides useful context 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?

Two sentences pack purpose, usage guidance, dataset list, and return behavior. No superfluous words; each sentence earns its place. Front-loaded with core purpose.

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

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

For a read-only tool retrieving recent rows, the description covers what it returns (latest rows, sorted newest-first) and how to filter (SoQL where). No output schema exists, but the behavior is adequately communicated given the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the dataset enum values in prose and providing examples of SoQL where clauses, reinforcing parameter meaning beyond the schema's formal descriptions.

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

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

The description states the tool retrieves recent records from open datasets by friendly name, avoiding Socrata IDs. It explicitly lists supported datasets and contrasts with web search and sf_query, clearly distinguishing it from siblings.

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

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

The description provides explicit when-to-use guidance, recommending this tool over web search for specific queries and delegating other uses to sf_query. Examples of appropriate queries and dataset names 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?

Annotations indicate a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds behavioral context: OAuth requirement, supported types, delivery channels, SMS cap, webhook signing, and auto-disable. 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?

Well-structured with front-loaded purpose. Each sentence adds value, though slightly lengthy. Could be more concise without losing information.

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

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

Covers requirements, types, params, delivery, limitations (SMS cap, webhook verification). Lacks return value details beyond 'new subscription id', but no output schema exists. Sufficient for a creation 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?

Input schema has 100% coverage, but description adds concrete examples for each type and delivery channel (e.g., items:["5.02"], min_spread_bps, webhook HMAC signing). Adds significant 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?

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This provides a specific verb and resource, and distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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?

Includes requirement 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' This tells when to use the tool. However, it does not explicitly exclude use cases or compare to alternatives, though the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns example questions with tool+argument shapes and is for onboarding. No contradictions; adds useful behavioral context beyond annotations.

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

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

Description is moderately long but well-structured, starting with common user phrasings, then explaining functionality and categories. Every sentence is informational, though it could be slightly more concise.

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

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

With no output schema, the description explains what is returned (category-bucketed questions with tool+argument shapes). It covers input, behavior, and output adequately for an onboarding tool. No missing critical details.

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

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

Schema covers topic parameter 100%, and description adds usage context (e.g., omit for full spread, pass specific topic). This goes beyond the schema's description, providing extra clarity for the agent.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool and argument shapes. It lists specific categories and positions itself as the onboarding entry point, distinguishing it from siblings like 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?

Explicitly says to use this tool first when unsure what Pipeworx can do, and for learning how to call meta-tools. Provides examples of how to call with or without topic. Does not explicitly mention when not to use, but context makes it clear.

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

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

Beyond the annotations (which indicate non-destructive mutation), the description explains the actual effect: deactivation rather than deletion, and that historical events remain accessible 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?

Two concise sentences that convey all necessary information without redundancy. Every sentence adds value, and the description is front-loaded with the core purpose.

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

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

Despite lacking an output schema, the description sufficiently explains the tool's effect (deactivation, historical data preservation) for a single-parameter mutation tool. No additional context is needed.

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

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

The schema already covers the parameter fully (type, description, required). The description does not add new semantic detail beyond what's in the schema, maintaining the baseline score for high coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the use of an id to cancel.

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 ownership enforcement ('you can only cancel your own subscriptions'), providing a critical usage constraint. No ambiguity about who can use this tool and on which subscriptions.

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 behavior. The description adds significant detail: the two processing paths (structured SEC EDGAR + XBRL for financial claims, grounded pipeline for others), output verdict set, inclusion of citations, and the fact that it replaces multiple sequential calls. No contradictions with annotations.

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

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

The description is well-structured, starting with trigger phrases, then explanation, then output details. It is somewhat verbose but each sentence adds value, and the length is justified by the tool's complexity.

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

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

Given the minimal schema and no output schema, the description fully covers what the tool does, its internal logic, expected output (verdict, value with citation, reasoning), and use cases. No missing essential information.

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

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

Input schema covers 100% of parameters with descriptions. The description adds value by explaining the tolerance_pct parameter's usage (overriding default, suggested range for hallucination detection) and provides examples for the claim parameter, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: verifying factual claims against authoritative sources. It provides explicit trigger phrases (e.g., 'fact check', 'verify the claim') and differentiates from sibling tools by emphasizing that it replaces multiple sequential calls (NL parsing, entity resolution, data lookup, comparison).

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and outlines two distinct processing paths for company-financial vs. other claims. While it does not explicitly list when not to use it, the purpose is well-scoped and contrasts with general Q&A tools like ask_pipeworx.

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