Data Fcc

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

Beyond annotations (readOnly, openWorld, etc.), description adds that default model is free, Anthropic requires BYO key and costs, and return shape includes per-model {score, confidence, signals, raw_response} plus combined view. No contradictions.

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

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

Three sentences: first explains core function and output, second explains cost model, third lists use cases. No fluff, well 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?

No output schema, but description details return shape. All parameters explained in schema. Use cases provided. Could mention rate limits or failure modes, but not critical for this tool type.

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 descriptions cover all 4 parameters (100% coverage). Description adds value by noting default model for 'models' parameter, cost implication for '_apiKey', and provides examples for 'entity' and 'context'. Adds marginal but useful 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?

Description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. It uses specific verbs like 'probe' and 'score' and distinguishes from sibling tools like 'ask_pipeworx' by focusing on broad AI visibility rather than just Pipeworx data.

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

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

Explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Explains default model and when to provide an API key. Lacks explicit when-not-to-use guidance 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?

With rich annotations present (readOnlyHint, openWorldHint, idempotentHint all true), the bar for additional disclosure was lower, and the description clears it substantially by revealing the pipeworx:// stable citation URI scheme, the scale of the underlying network (5,566 tools, 1462 sources), and the single-call routing behavior. It does not contradict any annotation. Minor deduction because it stops short of describing the structured return shape or failure behavior when no tool matches — though absence of an output schema shifts some burden, the trade-off is minor given annotations and schema coverage.

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 content is front-loaded with the most important message ('PREFER OVER WEB SEARCH') and proceeds logically from purpose to usage to escalation. However, it is notably verbose and promotional for a functional description — ALL CAPS phrases ('PREFER OVER WEB SEARCH', 'START HERE'), a very long list of data domains, and three stacked example queries stretch past efficiency. It uses roughly 150% of the words needed to communicate the same information.

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

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

Given this is a single-input router tool with rich annotations and no output schema, the description is complete: it covers input semantics, routing behavior, return format (structured answer + citations), tool capacity, and escalation paths to siblings. The only missing piece is an explicit example return shape (despite mentioning pipeworx:// URIs) and fallback behavior when no tool matches. Examples plus usage guidance make the agent's likelihood of misusing the tool low.

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

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

With 100% schema coverage and a single natural-language question parameter (plus 5 aliases), the semantic ceiling is low, and the description appropriately conveys that the question should be passed in natural language, demonstrating with examples like 'What was Apple's revenue in 2024?'. The description explicitly positions the tool as handling the argument-filling internally ('fills arguments'), which is helpful context for the agent not to overthink parameter construction. Slight deduction because the description doesn't strongly reinforce that all aliases are interchangeable, but the schema already handles that via repetitive property descriptions.

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

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

The description opens with an exceptionally clear statement of what this tool does: routes factual questions to a network of 5,566 tools and 1462 verified sources, returning structured answers with pipeworx:// citation URIs. It names specific data domains (SEC filings, FDA data, FRED/BLS, etc.) and differentiates itself from siblings by being the 'START HERE' default entry point versus ask_pipeworx_grounded (hallucination-resistant) and deep_research (multi-source fan-out). Technical redundancy is minimal and the description would not be confused with any sibling 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?

This is a model answer for usage guidelines. It provides explicit when-to-use trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), concrete example queries, an explicit statement of superiority over web search for these cases, and — critically — names specific alternatives with their exact use cases ('Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). Also clarifies that breaking-news queries are already handled internally via -news-feeds packs.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful context beyond these: it reveals the router's scope (5,566 tools), the fact that routing may change dynamically when candidates are tested, the current state (none active), and that it is a full working router despite being experimental. It also clarifies there is no fallback behavior, which complements the open-world and idempotent hints without contradicting them.

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

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

The description is well-structured and front-loaded, with the core identity stated first, followed by current state, usage guidance, and a clarifying note. It is slightly longer than strictly necessary but every sentence contributes useful context—no fluff. It balances detail with readability, earning a 4 for appropriate sizing.

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 a complex universal router, but there is no output schema, so the description should at least hint at the return shape. It says 'same response shape' but does not describe what that shape is, relying on knowledge of ask_pipeworx. It also omits details like error handling or rate limits, though annotations cover safety. For a beta router, the description is adequate but leaves some gaps for an agent unfamiliar with ask_pipeworx.

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

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

The input schema already describes all six parameters with full coverage (100%), including aliases and a description for each. The description does not add information about parameter values or formats beyond noting 'same arguments' as ask_pipeworx, which is redundant given the schema. Baseline of 3 applies because the schema handles parameter semantics, and the description adds little extra value.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router that handles questions across 5,566 tools. It differentiates itself from the stable ask_pipeworx by explicitly noting candidate routing improvements and calling out its current identical behavior, providing a specific verb (ask) and resource (router) with distinct scope.

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

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

It gives direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' This explains when to prefer it over the stable version, though it does not explicitly mention alternative tools like ask_pipeworx_grounded or state when *not* to use it. The phrase 'when you want the newest routing' is a clear context trigger, but could be stronger with exclusion criteria.

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

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

Annotations already declare read-only/idempotent safe behavior. The description adds essential behavioral detail: it returns evidence with verbatim quotes, can explicitly refuse with structured reasons, and costs an extra LLM call. No contradictions with annotations.

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

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

The description is dense yet every sentence carries weight: purpose, routing, return shape, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the core purpose and structured to inform selection 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 the tool's complexity, lack of output schema, and high-stakes use case, the description fully documents return values, failure modes, and cost/alternative guidance. No critical operational aspect is left unexplained.

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 documented as aliases for 'question'. The description adds no additional parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

Description states a specific verb ('answer') and resource ('Pipeworx'), and explicitly distinguishes itself from sibling ask_pipeworx by emphasizing 'grounded' extraction using only tool results. The return contract and refusal modes further clarify its unique role.

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 ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including the cost tradeoff of an extra LLM call. This goes beyond mere implication.

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

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

The description extensively discloses behaviors beyond annotations: low-confidence short-circuit, closed market handling, wide spread warnings, resolution-rule risk, and fan-out examples. Annotations already indicate readOnly and idempotent, and the description adds rich detail.

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

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

The description is lengthy and includes extensive details and examples. While well-structured with sections, it could be more concise. Every part is informative but the overall length reduces 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, no output schema, and high schema coverage, the description covers market resolution, fan-out patterns, response shapes, safety mechanisms, and resolution-rule risk. It is comprehensive for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'market' parameter accepts slug, URL, or question text, and details the 'depth' and 'include_raw' parameters. 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's purpose: researching a Polymarket bet by pulling Pipeworx data. It distinguishes itself from sibling tools like ask_pipeworx and polymarket_edges by being specifically for bet-level research.

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

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

Explicit use cases are provided: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It does not explicitly state when not to use, but gives clear context and examples.

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

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

The description reveals behavioral traits beyond annotations: it discloses data sources (SEC EDGAR/XBRL, FAERS), explains handling of off-calendar fiscal years, and notes results are sorted by primary metric. Annotations already indicate readOnlyHint and idempotentHint, and the description adds context without contradiction.

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

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

The description is a single, front-loaded paragraph that starts with example queries. It is dense but efficient, covering many details without unnecessary words. Could be slightly more structured (e.g., bullet points) but still earns a 4 for clarity and brevity.

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 complexity (two entity types, multiple data sources, up to 5 entities), the description covers essential aspects: what data is returned (paired data + citation URIs) and how it replaces many lookups. No output schema exists, so the description adequately explains returns.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the 'type' enum (company/drug) and the 'values' format (tickers/CIKs for company, drug names). It also provides context on what data is retrieved for each type, enhancing understanding beyond schema definitions.

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

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

The description clearly states it provides side-by-side comparison of 2-5 companies or drugs. It includes example queries like 'compare X and Y' and explains the data pulled for each type. It distinguishes itself from sequential single-pack lookups, matching the 'specific verb+resource' criterion perfectly.

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,' providing clear guidance on when to use this tool. It also includes example queries and specifies the number of entities (2-5), covering both when and why to use it effectively.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds context about returned fields and how to use results, exceeding annotation coverage.

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

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

Single sentence that efficiently conveys purpose, return data, and next step. No wasted words.

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

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

For a search tool with 3 parameters and no output schema, the description completes the picture by specifying return fields and linking to the metadata tool. Annotations further cover safety and behavior.

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

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

Schema covers all 3 parameters with descriptions. The tool description does not add additional semantic meaning beyond what is in the schema, so baseline 3 is appropriate.

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

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

Clearly states the tool searches the FCC Open Data catalog by keyword, mentions return fields (resource_id, name, description, category, update date), and distinguishes from siblings by indicating next steps (pass resource_id to query/metadata).

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

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

Implies usage for keyword-based search and provides follow-up action, but does not explicitly state when not to use it or compare with alternatives among siblings.

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

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

Annotations already declare readOnly/idempotent, but the description adds substantial context: account/paid-plan requirement, expected latency (15-60s up to ~90s), non-invention guarantee with gaps[], semantic excerpting of large records, contradictions[] for standard/thorough, and resolvable citation_uri. 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?

Front-loaded with the critical account requirement and structured into logical paragraphs (use cases, hop mechanics, output format, performance). Some redundancy (gaps[] mentioned multiple times) and length prevent a 5, but every sentence earns its place.

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

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

Despite no output schema, the description thoroughly explains the return packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field). It also covers prerequisites, sibling alternatives, performance bounds, and behavioral guarantees—complete for a complex research 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 both params fully, yet description enriches meaning: depth is explained with facet counts, hop behavior, and paid-tier distinction; question is clarified as accepting broad/multi-part natural language. This goes well beyond the schema's enum and type descriptions.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and clarifies decomposition and parallel routing. It explicitly distinguishes itself from open-web search and from siblings like ask_pipeworx, making its scope unmistakable.

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

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

Explicit when-to-use and when-not-to-use are given: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx', plus current-news guidance. It also names the alternative (ask_pipeworx) for unsigned-in users, providing concrete fallback direction.

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 safe read operation and idempotent behavior. Description adds valuable context: returns top-N relevant tools with schemas and examples, ready to call directly. 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?

Well-structured, front-loaded with purpose, each sentence adds value, no wasted words.

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

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

Given the tool's purpose, the description fully explains what it returns (tool names, descriptions, schemas, examples) and how to use it, making it complete for a discovery tool.

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

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

Schema coverage is 100%, and the description mentions query parameter aliases and examples. However, it does not add significant new meaning beyond the schema descriptions, so baseline 3 is appropriate.

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

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

Clearly states the tool finds tools by describing data/task, lists many domains, and distinguishes itself from siblings as the first tool to call for discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral details: fans out across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), lists return fields, notes patents sunsetting May 2025 and fallback mechanisms. 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 detailed (multiple sentences) but each sentence provides specific, useful information. Slightly verbose but not wasteful; could be tightened without losing substance.

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

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

No output schema, but the description enumerates all major return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes limitations (patents may soft-fail). Given the tool's complexity, this is very 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?

All 2 parameters have schema descriptions (100% coverage). The description reinforces with examples ('ticker AAPL' or 'zero-padded CIK 0000320193') and clarifies that names are not supported, adding 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 explicitly states 'full cross-source profile of a US public company in ONE parallel call', with specific verbs (profile) and resource (US public company). It distinguishes from sibling tools like resolve_entity by clarifying that names are not supported here.

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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explicitly states when not to use it (names not supported, use resolve_entity first). Clear guidance on alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is useful. No contradiction. Lacks mention of irreversibility or confirmation prompts but sufficient for a simple delete.

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

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

Two efficient sentences front-loaded with purpose and usage. No wasted words. Every sentence adds value.

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

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

Tool has one required param, no output schema, and simple behavior. Description covers purpose, usage context, and relationships with siblings. Fully adequate.

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

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

Schema coverage is 100% and the param 'key' is described as 'Memory key to delete' in both schema and description. Description adds no extra meaning beyond schema, so baseline 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying verb (Delete) and resource (memory by key). It distinguishes itself from siblings like 'remember' (store) and 'recall' (retrieve).

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with 'remember' and 'recall', guiding against alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds details on fetching the page, extracting title/description/key links, and emitting markdown format, which goes beyond annotations to explain the process and output.

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-loading the purpose in the first sentence, then explaining the process, and ending with use cases. Every sentence adds value with no wasted words.

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

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

Given the moderate complexity, full schema coverage, and no output schema, the description adequately explains the output format (markdown text blob) and placement (site-root/llms.txt), making it complete for agent understanding.

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 clear parameter descriptions (e.g., url with example, max_links with defaults). The tool description does not add additional semantics beyond the schema, so baseline score 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 generates a production-ready llms.txt file for any URL, specifying the verb and resource. It differentiates from sibling tools like ai_visibility_check and scan_competitor_ai_presence, which address different aspects of AI visibility.

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 concrete use cases (client indexing, personal project drafting, competitor auditing) that clarify when to use the tool. However, it does not explicitly exclude other scenarios or mention alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by listing return fields and explaining the include_inactive parameter's effect, 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, front-loaded with purpose, no verbose wording. Every sentence adds value.

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

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

For a simple list tool with one parameter, description covers return fields, default behavior, and use cases. Annotations handle safety. No output schema 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?

Schema coverage is 100%, but description adds meaning by implying default behavior (active only) and clarifying the purpose of include_inactive beyond the schema description.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and lists return fields. It distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly says to use this before adding more subscriptions or to find an id to cancel, providing clear usage context. Does not explicitly state when not to use, but is sufficiently clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the exact metadata returned (columns, types, row count, category, last-updated), which is beyond the annotation scope. There is no contradiction with annotations.

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

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

The description is a single, front-loaded sentence that efficiently conveys purpose, resource, and an example. Every word is necessary and earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema, rich annotations), the description is complete. It explains the input, the expected output fields, and provides an example. No further information is needed for an agent to use it correctly.

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

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

The input schema covers 100% of parameters, and the description duplicates the parameter example. The description does not add significant semantic meaning beyond what the schema provides (e.g., types, required). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to retrieve schema and metadata (columns, types, row count, category, last-updated) for an FCC Open Data dataset by resource_id. The verb 'Get' is precise, and the example '3xyp-aqkj' reinforces usage. It distinguishes itself from siblings by focusing on FCC Open Data metadata retrieval.

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

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

The description provides a clear context (retrieving metadata by resource_id) but does not explicitly state when to use it versus alternatives. There is no guidance on when not to use it or mention of limitations. The annotations (readOnlyHint, idempotentHint) imply safe usage, but the description itself lacks explicit usage guidelines.

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 all-false annotations, the description adds substantial behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against quota, returns a claim_token when filing without an account, and that passing the token later returns resolution status. It also explains the team reads digests daily and signal affects roadmap.

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 (150+ words) but every sentence carries useful information: purpose, categories, exclusions, claim workflow, rate limits, and guidance on what to include. It is front-loaded and logically organized, though slightly verbose; could be trimmed without loss, but not enough to drop to 3.

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 params, no output schema, and a nontrivial claim-token workflow, the description covers all bases: what to report, scope, exclusions, how to follow up, rate limits, and even style guidance ('don't paste the end-user's prompt'). It is fully sufficient for an agent to understand the tool's behavior and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra workflow semantics beyond the schema by explaining the claim_token flow: 'Filing without an account returns a `claim_token`; pass it back later...' This links parameters into a usage process, enriching meaning beyond individual field descriptions.

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

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

The first sentence explicitly states the verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback categories (bug, feature, data_gap, praise) and clearly distinguishes this from sibling tools by emphasizing it is ONLY for tools served by this Pipeworx connection, not other MCP servers.

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 'Use when' conditions (wrong/stale data, missing tool, praise) and explicit 'when not' with an alternative: 'if the tool came from a different MCP server... file it with that server instead.' Even clarifies uncertainty with 'Not sure? Pipeworx tool names are the ones this connection lists.'

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value beyond annotations by detailing the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradiction.

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

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

The description is concise (4 sentences) and front-loaded with purpose, followed by use cases and technical details. Every sentence adds value.

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

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

Given a single optional parameter, no output schema, and high schema coverage, the description covers use cases, data source, and caching. It mentions return types (top tools, packs, volume) but lacks explicit structure. Still adequate.

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

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

Schema has 100% coverage with one parameter ('window') and enum descriptions. The description adds usage context ('shorter windows surface what's hot... longer windows show steady-state demand'), which goes beyond the schema's enum labels.

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

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

The description clearly states the verb 'returns' and the resource 'top tools, top packs, and total call volume' over a recent window. It distinguishes from siblings 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?

The description lists three specific use cases (discovering hot data sources, confirming canonical tools, aligning use cases). It does not explicitly exclude alternatives, but provides clear context for when to use.

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

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

Annotations declare the tool read-only, open-world, and idempotent. The description adds significant behavioral context: scanning logic, Jaccard similarity anchor, placeholder filter, partition check with threshold, fill check against live order book depth, and response format. It discloses key constraints like 'skipped_low_similarity surfaces the rejected pair count' and 'do not trade it' when book edge is non-positive.

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 each sentence provides essential information. It is front-loaded with the core purpose and modes. While slightly dense, it maintains clarity and avoids redundancy. A more structured format (e.g., bullet points) could improve readability, but it is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description fully outlines the response structure (opportunities array with fields, partition check details, fill check). It covers all input modes, behavioral nuances, and references the sibling tool for custom sizing. The description is self-contained and leaves no major gaps for an AI 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?

Schema description coverage is 100% with clear descriptions for event and topic. The description adds substantial value beyond schema by explaining usage modes, example values ('fed-decision-may-2026'), and that full URLs are accepted for event. This compensates for the schema's brief 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 purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and provides specific examples, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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 explains when to use each mode: no args for a trending scan, event for a specific market, topic for cross-event scanning. It also warns against trading when realizable_edge_pp ≤ 0. While it doesn't mention alternatives like polymarket_edges or polymarket_kalshi_spread, the context is clear for 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=False. The description adds extensive behavioral details: caching strategy (1h KV-level keyed on all knobs), response structure including diagnostics, and edge cases like Fed bets. No contradiction.

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

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

The description is very long and dense, covering many technical details. While well-structured with clear sections (purpose, families, response, knobs, diagnostics), it could be more concise without losing essential information.

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

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

Given the complexity (9 parameters, no output schema), the description is exceptionally thorough. It covers the response structure, diagnostic fields, caching, and special cases (Fed bets), ensuring agents understand the output and behavior completely.

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

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

Schema coverage is 100%, but the description adds significant value for many parameters. For example, it explains the rationale behind slippage_pp (Polymarket fees, bid/ask) and min_partition_leg_kelly (why min_kelly doesn't filter). This exceeds bare 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 explicitly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It clearly defines the use case as 'what should I bet on today' and describes the three output segments, 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 explains when to use this tool (discovering opportunities without paging hundreds of markets) and details the three model families. However, it does not explicitly state when not to use it or mention 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 indicate read-only and idempotent; description adds rich behavioral detail: return structure (tracked[], expired[], snapshot_dates[]) and limits (60-day TTL, daily closes). 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 substantial but every sentence serves a purpose. Could be slightly more compact, but front-loaded with purpose and efficiently structured.

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

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

No output schema, yet description fully explains returned fields (tracked, expired, snapshot_dates) and their contents, plus limitations. Sufficient for agent to use correctly.

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

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

Schema covers both parameters with descriptions; description adds default values, clamp for days, and interprets window as snapshot family. Adds meaningful context beyond schema.

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

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

Description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age. It distinguishes a fresh wide edge from an old one, showing precise purpose and differentiation from sibling tools.

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

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

Implied usage is for historical edge analysis, but no explicit when-not-to-use or alternatives among siblings (e.g., polymarket_edges). Context is clear but lacks exclusions.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description does not contradict these and adds significant behavioral context: it explains what the tool returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.) and elaborates on the consequences of partial fills and forced directional risk. This goes beyond the annotations to disclose real-world behavior.

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

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

The description is dense but well-structured, with clear sections for SINGLE-MARKET and BASKET modes. Information is front-loaded with the core purpose. However, it is relatively long (over 150 words) and some sentences combine multiple concepts, which slightly reduces readability. Still, every sentence adds value and the structure earns a score above average.

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

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

With no output schema, the description fully compensates by detailing return values for both modes, including edge cases like thin legs and forced directional risk. It covers all 4 parameters, provides default values, and explains the tool's role in the arb/market-making workflow. The description is complete for guiding agent decision and invocation.

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

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

Schema description coverage is 100% but the description still adds meaning beyond the schema. For 'size_usd', it notes default and clamp range (10–1,000,000) not in schema. For 'side', it explains default logic for basket mode. For 'market' and 'event', it clarifies exclusivity ('REQUIRES one of'). These additions help the agent understand parameters better than schema alone.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating when to use it ('USE THIS before acting on any polymarket_arbitrage... or polymarket_edges trade above ~$500'). This provides specific verb-resource mapping and sibling differentiation.

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

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

The description provides explicit when-to-use guidance: before acting on arb signals or trades above ~$500. It also explains why this tool is necessary, warning that 'theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position (the dominant loss mode)'. This includes both usage context and exclusions.

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

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

The description adds extensive behavioral context beyond annotations: it explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning fields), details the compatibility conditions (matched_pairs, skipped_cross_type), and describes temporal alignment signaling. Annotations already indicate readOnly and idempotent, but the description enriches understanding significantly 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 comprehensive but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Each sentence adds value, though it is somewhat lengthy. It efficiently conveys a large amount of information without redundancy.

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

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

Given no output schema, the description adequately explains the response fields and safety warnings. It covers temporal alignment and compatibility indicators. However, it does not specify default behavior when no parameters are provided or how the tool handles errors, leaving minor gaps for complete understanding.

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

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

The input schema covers all 3 parameters with descriptions. The description adds value by explaining the topic list and the overriding behavior of explicit tickers. Schema coverage is 100%, so the description provides complementary context, earning a 4.

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

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

The title and description clearly state it computes 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons.

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 specifies two modes (topic shortcuts and explicit tickers) and when to use each. It warns that most pre-mapped topics return compatibility warnings and explains scenarios where spreads are not meaningful (non-equivalent bet shapes, temporal misalignment). This provides clear guidance on when to use the tool vs alternatives.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds value by explaining the SoQL syntax, the return format (JSON), and the parameter constraints (no leading $).

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, each efficiently carrying key information: purpose, syntax guidance, and output format. No filler or repetition.

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 7 parameters and no output schema, the description adequately covers the query language and return type. It could mention pagination limits or error handling but is sufficient for standard usage.

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

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

With 100% schema coverage, the description still adds meaning by clarifying that SoQL clauses should be provided without the leading '$', and by providing concrete examples (e.g., resource_id '3xyp-aqkj'). This prevents common user errors.

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 running a Socrata SoQL query against FCC Open Data by resource_id, with specific filter clauses and return format. It distinguishes itself from sibling tools like 'datasets' and 'metadata' by focusing on querying a dataset.

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 provides clear context for when to use the tool: to query a dataset with SoQL filters. It does not explicitly exclude alternatives or state when not to use, but the purpose is distinct enough among siblings.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by disclosing scoping ('Scoped to your identifier') and the behavior of omitting the key argument ('list all saved keys'). 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 three sentences, front-loaded with the core functionality. Every sentence adds essential information without redundancy. Very 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?

For a simple retrieval tool with full schema coverage and annotations, the description is complete. It covers purpose, usage, scoping, and pairing with related tools. No omissions.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description adds context with examples of what keys may contain, but it largely mirrors the schema. Meets baseline for well-documented parameters.

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

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

The description clearly states the verb 'retrieve' or 'list' and the resource 'value previously saved via remember' or 'all saved keys'. It distinguishes from sibling tools 'remember' (save) and 'forget' (delete) by explicitly pairing with them. Examples like 'user's target ticker, an address, prior research notes' provide concrete context.

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

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

The description explains when to use: 'to look up context the agent stored earlier' and 'without re-deriving it from scratch'. It also advises pairing with 'remember' and 'forget'. While it doesn't explicitly list exclusions or alternatives beyond those siblings, the context is clear enough for an agent to decide.

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

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

Adds context beyond annotations: describes return fields (source, citation_uri, raw payload), explains mark_read effect, and confirms idempotent behavior. Annotations already provide readOnlyHint, openWorldHint, etc., and description does not contradict 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?

Concise and well-structured: first sentence states purpose, followed by return fields, filtering options, and usage notes. No redundant information, every sentence adds value.

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

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

Given no output schema, description adequately covers return fields (source, citation_uri, raw payload), parameter behaviors, and practical usage notes (polling, alternative endpoint). It is complete for a read-only tool with well-documented parameters.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining the practical effect of mark_read and providing an example type ('sec_8k'), thus enhancing understanding beyond schema descriptions.

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

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

Clearly states the tool pulls fired events from the subscription feed, with specific verb and resource. Distinguishes itself from sibling tools like list_subscriptions by focusing on events.

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

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

Provides context on filtering by type and since, mark_read behavior, and mentions that polling works fine. Also notes an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, but does not explicitly compare to sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds rich behavioral context: fan-out to multiple sources, fallback behavior (GDELT→GNews), soft-fail for USPTO, and output structure (changes[] grouped by source with URIs). This goes beyond annotations.

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

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

The description is well-structured, starting with example queries for quick understanding. It is concise yet comprehensive, with every sentence providing value (source coverage, fallback, output format, alternative tool). No unnecessary words.

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

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

Given the tool's complexity (multiple sources, fallback, input formats) and no output schema, the description is thorough. It covers the tool's scope, limitations (USPTO soft-fail), output structure, and when to use the sibling tool. It is complete for effective use.

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

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

Schema description coverage is 100%. The description adds meaningful context: explains both ISO and relative formats for 'since', clarifies 'type' only supports 'company', and describes acceptable formats for 'value' (ticker or CIK). It enhances 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 a change feed for a company (SEC filings, news, patents) over a time window. It includes example queries and explicitly distinguishes from sibling tool 'entity_profile', making the purpose specific and differentiated.

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

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

The description explains when to use this tool (dynamic changes over time) and explicitly directs when not to use it ('Use entity_profile instead...'). It also provides practical usage hints for the 'since' parameter (e.g., 'Use "30d" or "1m" for typical monitoring'), giving clear guidance.

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

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

Beyond annotations (idempotentHint, destructiveHint), the description adds critical context: scoping by identifier, persistence differences between authenticated and anonymous sessions (24 hours vs permanent). 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?

Three sentences front-load the purpose and usage, then provide technical details. Every sentence is necessary 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?

For a write-only tool with no output schema, the description fully covers purpose, usage, behavioral traits, and pairing with siblings. No gaps.

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

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

Schema already covers both parameters with descriptions, but the description adds usage examples like 'subject_property' and explains the key-value pairing, enhancing meaning beyond the schema.

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

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

The description uses the specific verb 'save' and specifies the resource as 'data the agent will need to reuse later', clearly distinguishing from sibling tools like recall and forget.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and lists alternatives ('recall to retrieve later, forget to delete'). Provides concrete examples of what to store.

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

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

The description adds behaviors beyond the safe-read annotations: it explains that unresolved identifiers are explicitly listed under `unresolved` rather than omitted, that LEI/FIGI enrichment degrades gracefully with EDGAR identifiers still returning, and that each call cascades through multiple endpoints internally. These details inform expected failure modes and external dependencies, which is valuable for an agent.

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

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

The description is long but front-loaded with examples and a clear purpose. It is organized into 'SUPPORTED TYPES' segments and includes critical fallback behavior. Some redundancy exists (e.g., multiple examples followed by formal definition), and the final sentence about cascading is more meta than actionable, but the structure prevents confusion given 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?

With no output schema, the description carries the full burden of explaining return values. It does so thoroughly: labels with sources, explicit unresolved entries, parent ownership, and drug-specific outputs. It also covers degradation when external services are unavailable, which is important for an agent to trust the tool in variable conditions. This is a complete picture for a tool of this complexity.

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

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

Although the schema already covers both parameters with descriptions, the description enriches them significantly. For company, it lists accepted ticker, CIK, ISIN, or name and explains ISIN-to-LEI mapping. For drug, it specifies input as brand or generic name with examples. It also clarifies output semantics tied to these parameters, going well beyond the schema's minimal text.

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 immediately establishes the tool's role: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It is preceded by concrete example queries, making the verb-object relationship unmistakable. It also distinguishes from sibling tools by focusing on identifier resolution rather than entity profiles or comparisons, and it enumerates supported types ('company' and 'drug') with specifics.

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

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

The description explicitly instructs: 'Use FIRST whenever you have a name but need an ID.' This is a clear when-to-use directive. It also notes that resolve_entity replaces 2-3 manual lookups, implying it is the efficient first step. Although it doesn't name alternative tools or say 'do not use when', the guidance is strong enough for an agent to select this tool appropriately.

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

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

Annotations provide readOnlyHint, idempotentHint, etc. Description adds mechanism: probes each entity with `ai_visibility_check`, ranks by score, surfaces most/least recognized. No contradiction. Good extra context beyond annotations.

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

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

Two sentences, front-loaded with purpose. Every sentence adds value: what it does, how it works, when to use, return format. No fluff.

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

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

Despite no output schema, description specifies return: 'ranked list with score, confidence, signal density per entity'. Covers key parameters (models, apiKey, context, entities). Complete for tool complexity.

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

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

Schema coverage 100% so baseline 3. Description adds meaning beyond schema: notes first entity is 'subject' for narrative, explains models default behavior. Provides context on `context` parameter for disambiguation.

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 'Compare AI visibility across multiple entities side-by-side', specifying the verb (compare/scan), resource (competitor AI presence), and distinguishes from sibling tool `ai_visibility_check` which is for single entities. It is specific and actionable.

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 use case: 'useful for competitive AI-marketing audits' with example question. Implicitly contrasts with single-entity tool `ai_visibility_check`. Lacks explicit 'when not to use' but strong contextual guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses important behaviors: fans out to multiple services, partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed listing on timeout. No contradiction with annotations.

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

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

The description is a single dense paragraph but well-structured with front-loaded purpose. Every sentence provides value, though slightly verbose with some technical details that could be trimmed.

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

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

Despite no output schema, the description lists the summary block fields and explains partial failure handling, alternative ecosystems, and timing caveats. It is remarkably complete for a tool of this complexity.

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

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

Schema coverage is 100% with clear descriptions. The description adds extra context: scoped packages are accepted for the package parameter, and version defaults to latest when omitted. This adds meaning beyond the schema.

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

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

The description clearly states the tool performs a composite check for adding an npm package, covering licenses, advisories, version history, and bundle size. It specifies the output and ecosystem (NPM only), distinguishing it from any sibling tools.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also states alternatives for other ecosystems (PyPI, Maven, etc.) via deps.dev:version directly.

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

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

Discloses internal mechanics (BGE-base-en embeddings, cosine, 500-char windows, 200K char cap with truncation and flagging) 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?

Single dense paragraph with front-loaded purpose; every sentence adds value without redundancy.

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

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

Thorough explanation of tool's role, output characteristics (passages with offsets and scores), and integration with other tools 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 fully covers parameters; description adds context like truncation behavior, default limit, and example queries.

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?

Clear verb 'Semantic search' specifying the action, resource 'inside a fetched record', and distinguishing 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 states when to use ('record too big to cram into the prompt') and pairs with ask_pipeworx_grounded as an alternative.

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

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

The description adds significant behavioral context beyond annotations: requires OAuth account, phone verification for SMS, 10/day cap, webhook HMAC signing, auto-disable after 10 failures. Annotations indicate mutation (readOnlyHint=false), non-destructive, idempotent, and open to new types. Description aligns and enriches, with no contradictions.

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

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

The description is relatively long but efficiently structured: starts with core purpose and return, then auth constraint, then type-specific details, then delivery channels. Every sentence adds value, though slightly verbose in examples. Front-loaded with essential information.

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

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

Given the tool's complexity (multiple types, nested parameters, delivery options, auth requirements), the description is complete. It covers purpose, return (subscription id), constraints, and all delivery channel nuances. No output schema exists, but the return is described. No obvious gaps for agent decision-making.

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

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

Schema coverage is 100%, and the description adds substantial semantics: per-type examples (e.g., 'items:["5.02"] = officer change'), delivery object details (webhook signing, auto-disable), and specific constraints. This goes well beyond the schema descriptions, making parameter understanding highly actionable.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the action (create), resource (subscription to event stream), and outcome (returns id). The supported subscription types are listed, distinguishing it 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?

The description provides context on when to use the tool: for setting up persistent monitoring subscriptions. It includes prerequisites ('Requires a Pipeworx OAuth account'), types with examples, and delivery options. However, it does not explicitly state when not to use it or mention alternatives. The sibling context mitigates this, but a clearer exclusion would improve score.

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

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

Annotations already indicate read-only and idempotent. Description adds value by explaining the output format (category-bucketed example questions with tool+argument shapes) and behavior (call with no arguments for full spread or with topic). No contradictions.

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

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

The description is detailed but well-structured, front-loading the purpose and usage. Each sentence earns its place, though it could be slightly more concise without losing meaning.

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

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

Given the tool's simplicity (one optional parameter, no output schema, rich annotations), the description is fully complete. It covers output categories, usage scenarios, and argument behavior without gaps.

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

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

Schema coverage is 100% with one optional parameter. Description adds examples of topic values ('finance', 'pharma', 'betting') and explains how omitting it gives a cross-category spread, exceeding the schema's description.

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

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

The description clearly states the tool's purpose as an onboarding entry point for exploring Pipeworx capabilities. It uses specific verbs ('ask', 'learn', 'call') and distinguishes from sibling tools by focusing on discovering what questions to ask, not on answering them directly.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and gives example queries. Does not explicitly mention alternatives or when not to use it, but the context is clear that it's for initial exploration.

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, the description explains that the row is deactivated (not deleted) and historical events remain available via 'recent_alerts'. This adds critical behavioral context not captured by annotations.

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

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

Two sentences, front-loaded with the action, each sentence adds essential information without redundancy.

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

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

For a simple one-parameter tool with no output schema, the description fully explains behavior, ownership constraints, deactivation semantics, and relation to a related tool ('recent_alerts'). No gaps.

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

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

Schema coverage is 100% and the description does not add new meaning beyond what the schema already provides for the 'id' parameter. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', making the action unambiguous. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by describing the specific operation.

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: ownership is enforced (only own subscriptions) and deactivation preserves history via 'recent_alerts'. However, it does not explicitly state when not to use it or compare with alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it explains the return structure (verdict, value, citation, reasoning), clarifies the meaning of could_not_verify and unsupported, and warns callers about misinterpreting could_not_verify. This is exactly the kind of nuance annotations cannot convey, so a 5 is warranted.

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

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

The description is fairly long but well-structured and front-loaded with trigger phrases. It uses bold for the critical caveats and organizes the financial vs. general claim distinction clearly. Every sentence serves a purpose, though it could be tightened slightly without losing meaning.

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

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

Given the lack of an output schema, the description fully compensates by describing what the tool returns (verdict, value, citation, reasoning) and how to interpret ambiguous outcomes. It addresses edge cases, routing logic, and call-savings benefit, making it highly complete for a complex verification tool.

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

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

The input schema already provides descriptions for both parameters (100% coverage), so the baseline is 3. The description adds extra semantics for tolerance_pct (overrides wording-implied tolerance, recommended 1–2 for hallucination detection) and gives concrete claim examples, which is value beyond the schema.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources, with specific trigger phrases. It distinguishes scope (financial vs. other claims) and states it replaces a multi-step pipeline, but does not explicitly contrast with sibling tools like ask_pipeworx or deep_research.

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

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

The description states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for financial vs. other claims. However, it does not provide explicit exclusions or name alternative tools for non-claim queries, 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.