Permid

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

Adds significant context beyond annotations: mentions default model is free, Anthropic requires BYO key with direct payment, and returns per-model details including raw_response. No contradiction with annotations.

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

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

Two sentences covering action, parameters, return structure, and use cases. Front-loaded with purpose, 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?

Despite no output schema, the description explains the return structure (per-model score, confidence, signals, raw_response, combined view). Covers all parameters and use cases adequately.

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

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

Schema covers 100% of parameters with descriptions; description adds extra meaning (e.g., 'passed straight through to api.anthropic.com' for _apiKey, examples for entity and context). Adds 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?

Description clearly states the tool probes LLMs for brand visibility and scores it (0-100). Distinguishes from siblings like scan_competitor_ai_presence by specifying per-model scoring and probing individual LLMs.

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 cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Does not explicitly state when not to use or mention alternatives, but context is clear.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds meaningful behavioral context: it routes across 5,710 tools and 1,494 sources, fills arguments automatically, and returns answers with stable pipeworx:// citation URIs. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the most important routing guidance, but it is verbose and repeats itself: 'even if web search could also answer it' appears twice, and the list of example queries is long. It earns its place overall, but tighter editing would improve it.

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 single-required-parameter tool with no output schema, the description covers what the tool does, when to use it, how it handles the question, and what kind of response to expect (structured answer with citation URIs). It also points to deep_research for complex multi-part queries. Minor gaps like error handling or unsupported query behavior keep it from a 5.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description adds example phrasing and explains that the tool fills arguments itself, but it does not add per-parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a clear verb and resource: ask Pipeworx a natural-language question and get authoritative structured data with citations. It distinguishes itself from web search and deep_research, and lists concrete domains and examples, so an agent can tell what it does without ambiguity.

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

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

The description explicitly says to prefer this tool over web search for factual questions, gives trigger phrases like 'what is', 'look up', and 'get the latest', and provides examples. It also names the alternative deep_research for multi-part fan-out questions, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide readOnly/openWorld/idempotent and non-destructive hints. The description adds meaningful behavior beyond that: it is a full working router with no fallback, its routing can change live during candidate tests, and as of 2026-07-26 it exactly matches ask_pipeworx. 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?

Four sentences, front-loaded with identity and current state, and every sentence contributes useful information. The final sentence is slightly wordy, but it clarifies that this is not a degraded fallback but a full router, which is valuable.

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 an experimental router with no output schema, the description anchors expectations by saying the response shape is identical to ask_pipeworx, and it covers current state, usage, and experimental behavior. It could have described the exact response shape directly rather than deferring to the sibling, but since ask_pipeworx is available in the sibling list, the gap is minor.

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

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

Schema description coverage is 100% and the schema documents q, text, and input as aliases for question. The description only says 'same arguments' as ask_pipeworx without adding parameter-level detail, so the baseline 3 is appropriate given the schema carries the semantic load.

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 by identifying 'ask_pipeworx_beta' as the beta version of 'ask_pipeworx' and clearly defines it as an identical universal router with the same 5,710 tools, arguments, and response shape. It then distinguishes it by the live candidate routing improvements, so an agent can tell it apart from ask_pipeworx and ask_pipeworx_grounded.

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

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

It explicitly instructs 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared with the stable router. However, it never explicitly says 'use ask_pipeworx instead when you need stable production behavior'; that is only implied by 'beta' and 'experimental edge.'

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, open world), and the description adds substantial behavior beyond them: the exact success contract {answer, evidence (verbatim quote), confidence, source, fetched_at}, the refusal contract with five enumerated refusal_reason values, the hard constraint that answers come 'ONLY' from tool results, and the extra-LLM-call cost. Since there is no output schema, the description carries the full burden of explaining the return contract, and it does so thoroughly. 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?

Five sentences, each earning its place: purpose, mechanism/differentiation, return contract, when-to-use, and cost tradeoff. The critical framing ('hallucination-resistant', 'high-stakes') is front-loaded, and the when-not-to-use guidance lands last as a decision tie-breaker. The refusal_reason enum is verbose but each value is meaningful for agent handling. No filler and no repetition of annotation content.

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

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

For a tool with no output schema and 6 parameters, the description fully compensates: it specifies both success and refusal return shapes, enumerates refusal reasons, names the sibling alternative with a selection condition, and discloses the cost. Combined with 100% schema coverage and four safety annotations, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all 6 parameters are already documented in the schema; the baseline-3 applies. The description adds no per-parameter meaning, and given full coverage it does not need to. The 'question' parameter is already well-specified in the schema as natural language with aliases (query, q, prompt, text, input).

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 names a specific mode — 'hallucination-resistant answer mode for high-stakes reads' — and states the mechanism: routing across 5,710 tools/1,494 sources, filling arguments, fetching data, then extracting the answer using ONLY what the tool result contains. It explicitly contrasts itself with the sibling ask_pipeworx ('Same routing as ask_pipeworx'... 'prefer ask_pipeworx'), so an agent can distinguish this variant without opening the schema.

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

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

Gives an explicit when-to-use rule: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' reinforced with concrete high-stakes domains (financial verdicts, legal claims, medical lookups, public statements). It also gives an explicit when-not-to-use rule: 'prefer ask_pipeworx for casual lookups,' with the cost rationale ('Costs one extra LLM call'). This is exactly the alternative-selection guidance the rubric asks for.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It details the fan-out process, response shapes, market match confidence, safety short-circuits, cancellation rules, and fallback behavior. This comprehensive disclosure aligns with annotations and provides critical behavioral context for correct use.

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 quite long and dense, covering many technical details. While the information is valuable, it could be more concise. It is front-loaded with the purpose but includes extensive examples and edge-case handling that, while complete, reduces conciseness.

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 classifiers, fan-out, safety behaviors), the description thoroughly covers response shapes, edge cases (low-confidence, closed markets, wide spreads), and important fields like cancellation rules. It compensates for the lack of output schema by detailing what the agent will receive, making it highly 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?

While the input schema covers 100% of parameters, the description adds significant value by explaining the 'market' parameter's accepted formats (slug, URL, question text), the 'depth' parameter's values, and 'include_raw' default and use cases. Examples further clarify usage, exceeding baseline schema descriptions.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, with multiple input formats. It provides specific use cases ('should I bet on X'). However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or ask_pipeworx, missing a chance to clarify when this tool is preferred over alternatives.

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

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

The description gives explicit use cases and examples for when to use this tool (e.g., 'should I bet on X'). It also describes behavior for various scenarios (low-confidence matches, closed markets, wide spreads). However, it does not explicitly state when NOT to use it or compare to sibling tools, lacking clear exclusions.

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

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

Annotations already mark it as read-only, idempotent, non-destructive. The description adds detailed behavioral context: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, result sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

A single, front-loaded paragraph with example queries. Every sentence serves a purpose: usage examples, preference rule, data sources, result behavior. No wasted words.

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

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

Despite no output schema, the description adequately explains what data is returned (paired data + citations) and how it's sorted. Covers all necessary context for a comparison tool with clear input constraints.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by specifying tickers/CIKs for companies and drug names, and noting the sorted-output behavior. Slightly more than the 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 the tool provides side-by-side comparisons of 2–5 companies or drugs, with explicit example queries ('X vs Y', 'rank these companies'). It distinguishes from sequential lookups, making the purpose unambiguous.

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

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

It explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear use-case guidance. It lacks explicit exclusions or alternatives for non-comparison queries, but sibling tools like entity_profile fill that gap.

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

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

Annotations already mark this read-only/open-world/idempotent, and the description adds substantial behavior beyond that: decomposition into facets, parallel routing across 5,710 tools, findings packet shape, gaps[] that are never invented, contradictions[], hop fields, citation_uri semantics, semantic excerpting, and latency expectations. No annotation contradiction exists.

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 dense and front-loaded with the account requirement and the key scope statement. There is minor redundancy in the repeated 'use ask_pipeworx instead' guidance, but every paragraph contributes valuable selection and invocation 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?

There is no output schema, so the description must explain return values and it does: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop fields, and citation fetchability. Combined with auth requirements, alternatives, depth semantics, and latency, the agent has everything needed to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds useful execution context beyond the schema, such as the paid gate for thorough, latency ranges, and clarification that the question should be natural language and can be broad. Some depth-tier detail is redundant with the schema, but the added context justifies a 4.

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

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

The description names a specific capability: grounded multi-source research across 1494 structured data sources in one call. It explicitly says this is NOT open-web search and contrasts with ask_pipeworx for single lookups, so an agent can distinguish it from siblings.

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

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

It gives explicit if/then routing guidance: use ask_pipeworx if not signed in or for single lookups; use deep_research for broad/multi-part questions over structured data. It also differentiates depth tiers, including the paid requirement for thorough.

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, and destructiveHint=false. The description adds valuable behavioral context: results include full input schemas with curated examples and are 'ready to call directly, no second schema lookup needed.' This disclosure goes beyond the annotations without contradiction.

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

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

The description is informative and front-loaded with the core purpose. While slightly verbose, every sentence contributes useful information (when to call, output specifics). It could be more concise but remains efficient for the complexity it covers.

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

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

Given the tool's simplicity (no output schema, few required parameters, no nested objects), the description is nearly complete. It explains the tool's function, usage timing, and output characteristics. Minor gaps include no mention of error handling or rate limits, but these are acceptable 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 description coverage is 100%, with each parameter having a description in the input schema. The description mentions that the tool accepts natural language queries and lists aliases, but it adds little semantic value beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description starts with 'Find tools by describing the data or task,' which clearly and specifically states the tool's purpose. It lists many example domains and emphasizes returning top-N relevant tools with full schemas and examples, distinguishing it from sibling search/discovery tools like search_entities 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 explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use it. However, it does not explicitly state when not to use it or mention specific alternatives beyond listing sibling tool names.

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, not destructive. Description adds valuable context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, and notes soft-fail for patents. 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 thorough but verbose. It lists many details and examples, which helps clarity but sacrifices conciseness. Structure is good with front-loaded examples.

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

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

Given no output schema, description fully covers return values, sources, and behavioral quirks (e.g., patent sunset). It addresses all relevant aspects for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats parameter info (type only 'company', value must be ticker or CIK) from schema but does not add new depth beyond examples.

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

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

The description clearly states the tool's purpose: provide a full cross-source profile of a US public company. It gives specific example queries ('Tell me about X', 'company profile for Microsoft') and explicitly contrasts with chaining single-pack lookups.

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

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

Description includes explicit guidance: ALWAYS PREFER over chaining when user asks for holistic view. It also specifies limitations (only companies, not names) and directs to resolve_entity for names.

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. Description adds context about clearing sensitive data but does not clarify idempotency behavior or error handling beyond what annotations provide.

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

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

Two sentences: first states action, second gives usage guidance and pairing. No wasted words, front-loaded.

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

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

Covers purpose, usage context, and sibling relationships. Lacks details on return value or behavior when key does not exist, but acceptable for a simple 1-parameter tool without output schema.

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

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

Schema coverage is 100% with clear parameter description ('Memory key to delete'). Description merely repeats the concept of 'by key' without adding new meaning.

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

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

Description states 'Delete a previously stored memory by key' with specific verb and resource. Distinguishes from siblings by mentioning 'Pair with remember and recall'.

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, task is done, or to clear sensitive data. Mentions pairing with alternatives (remember, recall) but lacks explicit when-not-to-use scenarios.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/links, and emits standard markdown format, complementing annotations without contradiction.

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

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

The description is a single front-loaded paragraph that efficiently conveys purpose and usage. Some redundancy ('production-ready', 'cleanly') could be trimmed, but overall concise.

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

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

With 2 parameters, no output schema, and good annotations, the description covers output format and primary use. It lacks error handling for invalid URLs, but is reasonably complete for a simple generation tool.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds default and max for max_links, but overall adds minimal beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (generate) and resource (llms.txt) for AI crawlers. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description lists explicit use cases (client indexing, own project drafting, competitor auditing), providing clear context. However, it does not mention when not to use the tool or suggest 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 provide safety traits (readOnly, idempotent, non-destructive). The description adds significant behavioral context: it discloses the source API, the return structure (key 'raw'), and the extractable fields (name, LEI, RIC, etc.), enhancing understanding beyond the annotations.

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

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

The description is two concise sentences with no wasted words. The first sentence states the core action with a concrete example, and the second explains the output and potential use cases. Information is front-loaded and easy to parse.

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

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

Given the tool's simplicity (one parameter), rich annotations, and presence of an output schema, the description provides complete context. It explains the tool's purpose, example input, and what to expect from the output, leaving no major 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 schema already describes the parameter type and example. The description repeats the example but adds no new meaning or constraints beyond what the schema provides, so a 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 action ('Fetch') and the resource ('raw JSON-LD PermID record for a numeric PermID'). It specifies the exact return structure and gives an example PermID, making the tool's purpose unambiguous and differentiated from siblings like resolve_entity or search_entities.

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

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

The description implies usage for retrieving raw linked-data records but does not explicitly guide when to use this tool versus siblings (e.g., resolve_entity, entity_profile). However, the clear purpose and mention of 'raw JSON-LD' effectively imply its niche.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by specifying that it returns only active subscriptions by default and listing the exact return fields, which is useful context beyond the annotations.

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

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

The description is three sentences long, each sentence adding essential information: purpose/return, default behavior, and usage guidance. No wasted words, efficient and front-loaded.

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

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

For a simple list tool with one optional boolean parameter and no output schema, the description adequately covers behavior and return values. It could mention limits or pagination, but it's sufficient for typical use.

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

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

The schema coverage is 100%, so the description does not need to add parameter details. The description does not repeat or extend the parameter information beyond what the schema provides, which is appropriate. Baseline 3.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', and specifies return fields. It effectively differentiates from sibling tools like subscribe and unsubscribe, which are mutation tools.

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

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

The description explicitly advises using the tool to review monitored subscriptions before adding more or to find an id for cancellation, providing clear context. It stops short of explicitly stating when not to use, but the guidance is strong.

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

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

Annotations are all false and give no useful signal, so the description carries the full burden. It discloses the claim_token flow for anonymous submissions, follow-up usage, rate limiting (5 per identifier per day), free usage vs quota, and that the team reads digests daily. This is rich behavioral context with no contradiction to 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 longer than ideal but front-loaded with the core purpose, and every sentence carries useful information. Slight redundancy in the scope warning (ONLY for Pipeworx connection / different MCP server) keeps it from a perfect score, but overall it is dense and well-structured.

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

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

With no output schema and all-false annotations, the description covers the full operational lifecycle: when to use, message content constraints, claim_token mechanics, rate limits, and cost. It preempts common mistakes (reporting other servers' tools, pasting user prompts), making it complete for a feedback tool with follow-up.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the claim_token lifecycle (pass it back later to read status) and message framing rules ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which go beyond the schema's 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 'Tell the Pipeworx team something is broken, missing, or needs to exist' and names specific feedback categories (bug, feature/data_gap, praise). This clearly identifies the tool's verb, resource, and scope, and distinguishes it from the sibling research/query tools by being the dedicated feedback channel.

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

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

It explicitly states when to use the tool (bug, feature/data_gap, praise) and when not to (issues with other MCP servers), with an alternative: 'file it with that server instead.' It also clarifies identification of Pipeworx tools ('the ones this connection lists'), providing unambiguous selection guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: derived from CF analytics-engine, no PII, and cached 5min-1h depending on window. This goes beyond annotations to inform agents about data freshness and privacy.

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—about five sentences, front-loaded with the primary output. Every sentence adds value: results, use cases, data derivation, and caching behavior. 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?

With one optional parameter, rich annotations, and no output schema, the description adequately explains the high-level output (top tools, packs, call volume). However, it lacks a concrete example of the return structure, which would make it fully complete for an agent invoking it.

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

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

Schema coverage is 100% and the schema already defines the 'window' parameter with an enum. The description adds nuance by explaining 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which enriches the semantic understanding for the agent.

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

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

The description clearly states 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It specifies the verb (returns) and the resource (trending data), and the explicit mention of three use cases distinguishes it from siblings like 'discover_tools'.

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

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

The description lists three concrete use cases: discovering hot data sources, confirming canonical tool, and aligning with agent needs. While it does not explicitly state when not to use the tool, the contexts provided are clear and actionable.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond annotations: semantic anchor (Jaccard similarity >=0.30), partition filter (placeholder slugs, >20% placeholder fraction returns null), fill check (realizable edge vs theoretical edge). 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 detailed and front-loaded with core functionality. Every sentence adds value, but it is somewhat verbose (e.g., explaining semantic anchor and partition filter in detail). Still well-structured with clear sections for each mode and the fill check.

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 (multiple modes, semantic anchor, partition filter, fill check) and no output schema, the description is comprehensive. It covers input parameters, response structure (opportunities[], partition_check with fields), and edge cases (skipped_low_similarity, placeholders filter, fill check logic). Leaves no major 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 descriptions for event and topic. The tool description adds value by explaining what each parameter does in practice (event slug or full URL, topic as seed question), when to use each, and the underlying logic (cross-event scanning, semantic anchor). This enriches the schema-provided information.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no args (trending scan), event (single-event, recommended), and topic (cross-event). This separates it from siblings like polymarket_edges or 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 guides when to use each parameter: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'or topic for a themed cross-event scan'. It recommends event for specific markets and explains the fill check when not to trade. However, it doesn't explicitly name alternative tools for similar tasks.

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

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

The description adds significant behavioral context beyond annotations. It details three model families, caching behavior (1h KV), filters (placeholder-slug, Fed bets), and diagnostic output. Annotations declare readOnlyHint and idempotentHint, which the description aligns with by describing a read-only scanning operation.

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

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

The description is well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and front-loaded purpose. It is somewhat long but justified given the complexity. 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 the absence of an output schema, the description thoroughly explains the response structure (by_segment, diagnostics, per-opportunity fields). It covers caching, filtering, and tradeable-edge knobs, making the tool fully understandable without external documentation.

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

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

Input schema has 100% description coverage, so baseline is 3. The tool description adds extra usage context for several parameters (e.g., when to bump slippage, min_partition_leg_kelly explanation) beyond the schema descriptions, providing additional guidance for the agent.

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

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

The description clearly states it scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and identifies the resource ('top Polymarket markets'). It distinguishes from siblings like 'polymarket_arbitrage' by focusing on edge detection rather than pure arbitrage.

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

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

The description explicitly states it's built for 'what should I bet on today' and helps agents discover opportunities without paging hundreds of markets. It implies when to use (for daily edge scanning) but does not explicitly provide when-not-to-use instructions or compare to all siblings.

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

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

The description goes well beyond annotations by detailing the time-series analysis, trend classification (new, widening, stable, decaying), decay computation, expired opportunities, snapshot dates, and limitations (60-day TTL, daily closes). No contradictions with annotations (readOnly, idempotent).

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 could be more structured (e.g., bullet points for response fields). It is front-loaded with purpose and key points, and all sentences are informative. Slightly verbose but efficient for the complexity.

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

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

For a tool with no output schema, the description thoroughly explains return fields (tracked, expired, snapshot_dates), their meanings, and constraints (TTL, snapshot gaps). It covers all necessary context for correct use, making it highly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds default values and clamping (days max 30 vs schema clamp 2-30) but does not provide substantial additional meaning beyond the schema. Minor discrepancy in max value does not significantly affect understanding.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It uses a specific verb ('answers') and resource ('edge persistence'), and distinguishes itself from the sibling 'polymarket_edges' by focusing on historical trends rather than current edges.

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

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

The description implies usage for understanding edge history and decay, but it does not explicitly contrast with alternatives like 'polymarket_edges' or other sibling tools. No explicit 'when-to-use' or 'when-not-to-use' guidance is provided, leaving the agent to infer context.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds behavioral details: walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains basket risks (thin_legs, forced_directional_risk). No contradiction with annotations; adds substantial context.

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

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

The description is front-loaded with purpose and mode explanations. However, it is verbose (multiple paragraphs). Every sentence adds value, but could be more concise. A tighter structure would improve clarity.

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

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

Despite no output schema, the description lists all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) for both modes, explains basket risks, and covers edge cases. For a complex tool with two modes and multiple return values, it provides complete context for an AI agent.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds meaning beyond schema: explains default behavior for 'side', clarifies mode selection for 'market' vs 'event', and interprets 'size_usd' for buys/sells and basket notional. This enriches parameter understanding.

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

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

The description explicitly states the tool's purpose: 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, and specifies it should be used before acting on polymarket_arbitrage or polymarket_edges signals, differentiating it from siblings.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial fills convert arb to directional position), giving clear when and why 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 only declare read-only, open-world, idempotent, non-destructive safety. The description adds substantial runtime behavior: compatibility_warning and compatibility_codes, skipped_unclassified legs, low_confidence_pairs, temporal_alignment, skipped_cross_type/subtype counters, and the exact meaning of every code. It contradicts none of the annotations and carries the full behavioral disclosure burden.

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

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

The description is dense and long, but it is well-organized with labeled modes, CAPS field names, and code lists, and almost every sentence carries operational information. It is not minimal, but the length is justified by the tool's complexity and the absence of an output schema.

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

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

For a tool with no output schema, optional params, and complex comparison semantics, the description covers input modes, response fields, safety flags, skipped-pair counters, temporal alignment, and the all-important caveat that pre-mapped does not mean tradeable. Nothing needed to correctly invoke and interpret the tool appears missing.

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

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

The schema already documents all three parameters, but the description enriches them meaningfully: it defines the exact topic shortcut list, explains that explicit ticker/slug overrides the topic-mapped side, and describes how the two modes change the data flow. This is substantial value beyond the structured schema coverage.

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

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

The opening sentence names the exact object ('cross-venue spread') and the specific operation (comparing the same resolving question across Kalshi and Polymarket). The body further distinguishes two invocation modes: pre-mapped macro topics and explicit event pairings, which sets it apart from the generic research and arbitrage 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?

The description clearly explains how to invoke topic mode versus explicit mode, and warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not equal tradeable. It stops short of explicitly naming sibling alternatives with when-to-use versus when-not-to-use conditions, so there is clear context but no direct exclusion guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds value by clarifying scoping (by identifier) and the behavior when the key is omitted (lists all keys). 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, no wasted words. The description is front-loaded with the core action and supplementary details follow efficiently.

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

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

The tool is simple (one optional parameter, no output schema), and the description covers retrieval, listing, scoping, and pairing with related tools. No gaps remain for an agent to misuse it.

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

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

Schema description coverage is 100% with one parameter. The description adds meaning beyond the schema by explaining that omitting the key lists all saved keys, which is not in the schema property 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 uses specific verbs ('Retrieve', 'list') and clearly identifies the resource (values saved via 'remember'). It distinguishes from siblings like 'remember' and 'forget' by mentioning 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?

The description explains when to use the tool ('to look up context the agent stored earlier') and pairs it with 'remember' and 'forget'. It does not explicitly state when not to use it, but for a simple retrieval tool, this is adequate.

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

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

Annotated as readOnly, idempotent, openWorld, and not destructive. Description adds behavioral details: the feed is persisted, mark_read flags events as read affecting subsequent calls, and return fields. These go beyond the annotations, providing useful transparency 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?

Description is about 4 sentences, front-loaded with purpose. Each sentence adds value (return fields, filtering, mark_read behavior, polling alternative). No fluff, efficient structure.

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

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

For a read-only list tool with no output schema, it adequately describes return values and behavior. Covers all key parameters and the feed persistence. Missing details like pagination or error handling, but these are not critical given the tool's simplicity and annotations.

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 5 parameters have descriptions in the input schema (100% coverage). The description adds examples for 'type' and 'since', and explains the effect of 'mark_read', but does not provide extensive new meaning beyond the schema. Baseline 3 is appropriate because schema coverage is high, and description adds marginal 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?

Description clearly states the tool pulls fired events from the subscription feed, specifies return fields (source, citation_uri, raw payload), and distinguishes it from sibling tools like subscribe/unsubscribe that manage subscriptions. The verb 'Pull' and resource 'fired events' are specific.

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

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

Provides clear guidance on filtering by type and since, and the mark_read feature. Mentions that polling works fine and offers an HTTP alternative (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, implying when to use the tool vs. direct access. Could be more explicit about when not to use, but overall good context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: parallel call, fan-out to multiple sources, fallback mechanism, and return structure (changes[] + total_changes + URIs). No contradictions.

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

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

The description is dense with information but efficiently organized. It front-loads examples and purpose, then covers sources, parameters, and alternatives. Slightly long but earns its length with utility.

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, it explicitly describes return format. It covers all necessary aspects: purpose, parameters, data sources, fallback, limitations, and sibling differentiation. No gaps remain.

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

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

Schema coverage is 100%, but description enriches the `since` parameter with specific relative shorthand examples and a recommendation ('30d' or '1m'). It also clarifies that `value` accepts ticker or CIK, adding value over the 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 starts with clear examples and states the tool's purpose: a change feed for a company in the last N days/weeks/months. It explicitly distinguishes from sibling `entity_profile`, stating exactly when to use that instead.

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

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

Provides explicit when-to-use guidance (e.g., 'Use entity_profile instead for static profile') and usage examples. It also describes fallback behavior (GDELT to GNews) and soft-fail for USPTO, giving clear context for appropriate use.

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

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

Annotations provide idempotentHint=true, but description adds important behavioral details: scope by identifier, persistence differences for authenticated vs anonymous users (24 hours). 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?

Description is well-structured and front-loaded with the main action. Each sentence adds value, though slightly verbose. Could be more concise but overall effective.

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

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

Tool is simple with no output schema. Description explains storage as key-value pair and scope. Adequate for understanding behavior and return (confirmation not 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% with good descriptions. Description adds context about key-value pair and example keys, but schema already includes examples. Extra value from scope info, but not necessary for parameter understanding.

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

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

Clearly states the tool saves data for later reuse across conversations or sessions. Verb 'save' and resource 'data' are specific. Distinguishes from sibling tools 'recall' and 'forget' by mentioning them.

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

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

Explicitly describes when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' Also advises pairing with recall and forget, providing clear usage context.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false). It discloses that each call cascades through multiple internal endpoints, replacing 2-3 manual lookups. It also explains graceful degradation: LEI/FIGI enrichment degrades gracefully when GLEIF or OpenFIGI is unavailable, but EDGAR identifiers still return. This level of detail about fallback behavior and internal composition is valuable and does not contradict any annotation.

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 quite long (multiple paragraphs) with dense detail. While well-structured (examples first, then specifics), it could be more concise by reducing redundancy (e.g., repeated mentions of supported types, internal cascading). Some sentences are verbose for a tool description, making it less scannable.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns: canonical identifiers with source labels, explicit unresolved identifiers, and fallback behavior. It covers both entity types, input formats (including ISIN for company), and the graceful degradation of LEI/FIGI enrichment. This is complete for a lookup tool given the annotations provide safety guarantees.

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

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

Schema coverage is 100% (both parameters documented). The description adds meaning by giving concrete input examples for the 'value' parameter (e.g., 'AAPL', '0000320193', 'CH0038863350') and explaining that ISIN resolves to legal entity via GLEIF mapping. For the 'type' enum, the description expands on what each type resolves to (e.g., company returns multiple identifiers with source labels). This enriches the schema definitions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with concrete examples like 'What's the ticker for...' and 'find the CIK for...'. It distinguishes itself from sibling tools like get_entity or search_entities by being the primary name-to-ID resolver, explicitly advising 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly tells agents to use this tool first when they have a name but need an ID, and lists the two supported entity types with their resolution details. However, it does not explicitly state when NOT to use it (e.g., if the agent already has an ID), but the 'Use FIRST' guidance strongly implies that alternative tools like get_entity or entity_profile should be used after resolving.

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, open-world, idempotent, and non-destructive behavior. The description adds specific behavioral details: it probes each entity, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. 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 two sentences plus an illustrative quote. It is concise, front-loaded with the main action, and every sentence contributes meaning. No unnecessary words 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 the complexity (multiple entities, ranking, models), the description adequately explains the process, output fields, and supported options. The inferred return structure (score, confidence, signal density) is sufficient 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 has 100% coverage, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' for narrative purposes and that context is shared across probes. This enriches the parameter meaning beyond the schema.

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

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

The description clearly states the tool's action: 'Compare AI visibility across multiple entities side-by-side.' It specifies the resource (competitor AI presence) and distinguishes itself from siblings by noting it probes each entity with ai_visibility_check and ranks them. The example query reinforces the purpose.

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

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

The description provides clear context for when to use this tool: 'Useful for competitive AI-marketing audits.' It gives a concrete example question. However, it does not explicitly exclude cases or mention alternative tools (like ai_visibility_check for a single entity), leaving some ambiguity.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it fans out to two external sources, handles partial failures gracefully, and notes that bundlephobia's first measurement can take 5-30 seconds, with sources_failed listing timeouts. 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 fairly long but well-structured, starting with the tool's purpose, then usage guidance, output summary, ecosystem scope, and behavior notes. Every sentence adds value, though slightly more conciseness could be achieved without loss of clarity.

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

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

Despite having no output schema, the description enumerates the return fields (summary block with is_latest, license, etc., per-advisory detail, links, and recent alternative versions). It also explains partial failures and that bundlephobia may time out. For a two-parameter tool, this is comprehensive.

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

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

Schema coverage is 100% with both 'package' and 'version' having descriptions. The description adds that 'version defaults to the latest published version when omitted' and that scoped packages (e.g., '@types/node') are accepted for 'package'. This clarifies semantics beyond the schema.

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

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

The description clearly states it is a composite check for npm packages, combining license, advisories, version history, and bundle size info. It uses specific verbs ('fans out') and resources ('deps.dev', 'bundlephobia'), and distinguishes from sibling tools which focus on AI, search, or other domains.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing clear usage context. It also notes the tool is NPM-only in v1, but does not explicitly state when not to use it or list 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, openWorldHint, and destructiveHint. The description adds value by specifying return fields (PermID, type, name, brief context) and the search scope, consistent with annotations. No contradictions.

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

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

Two sentences, front-loaded with purpose and output, followed by a clear directive for related tool usage. Every sentence adds value with no redundancy or filler.

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

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

Given the presence of an output schema, the description sufficiently covers purpose, output fields, and a sibling tool reference. It could mention default limit or pagination, but the schema provides bounds. Overall complete for a search tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description does not add new parameter detail beyond stating the search is 'by name' (implicitly tying to query). It adds no semantics for limit or entity_type, but the schema already covers them adequately.

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 'Search' and the resource 'PermID' along with the types of entities (organizations, people, instruments, quotes) and what it returns. It distinguishes itself from sibling tools like get_entity by specifying the scope of results (brief context vs. full record).

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 directs users to use get_entity when they need the full linked-data record, providing clear when-to-use guidance. It does not mention other siblings like resolve_entity, but the single alternative is sufficient for common cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds technical details beyond annotations: embedding model (BGE-base-en), similarity (cosine), window size (500-char overlapping), character cap (200K), and truncation notification. 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-loaded with core purpose, no fluff. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains return format (top-N passages with offsets and similarity scores) and truncation behavior. For a 3-parameter tool with clear annotations, this is comprehensive.

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 reiterates parameter purposes with examples (e.g., natural-language query examples) but does not add significantly new semantic meaning beyond the schema descriptions.

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

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

The description clearly states it performs semantic search inside a fetched record, gives concrete examples (SEC filing, article, tool result), and explains benefits (saves context, returns relevant passages with offsets). It distinguishes from siblings by explicitly mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt.' Also explains how to pair with ask_pipeworx_grounded, and mentions the 200K char cap with truncation behavior.

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

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

The description discloses behavioral traits beyond annotations: it creates a persistent subscription, returns an id, requires OAuth, and details delivery channel limitations (SMS cap, webhook auto-disable). Annotations indicate idempotentHint=true, but the description does not clarify idempotency behavior, which is a minor gap.

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 concise for its complexity, with a clear hierarchy: purpose, requirement, type list, delivery options. It is not overly verbose, though some details could be moved to the schema.

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

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

For a tool with 3 parameters (including nested objects) and no output schema, the description covers all necessary aspects: prerequisites, type-specific parameters, delivery options, return value, and behavioral constraints. It is complete for the tool's purpose.

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 significant meaning beyond the schema with examples, constraints, and detailed explanations for each type and delivery channel (e.g., phone verification, webhook signing). This fully compensates for any lack of detail in the schema.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'. The title 'Subscribe to Alerts' reinforces the purpose.

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

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

The description provides explicit prerequisites (OAuth account) and lists supported types with their parameters. It implicitly distinguishes when to use this tool vs. siblings (e.g., for other actions use 'unsubscribe' or 'list_subscriptions'). However, it does not explicitly state when not to use it.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns 'category-bucketed example questions' with 'exact tool + argument shape', drawn from a 'live catalog of thousands of tools'. No contradiction with annotations.

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

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

The description is relatively long but every sentence adds value. It front-loads with common natural language queries and then provides structured details about the output and usage. It's concise given the complexity of the tool's purpose.

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

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

Given the tool has only one optional parameter, no output schema, and serves as an onboarding entry point, the description covers all essential aspects: purpose, output format, parameter usage, and when to invoke it. It is complete for its role.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema by listing example topic values ('finance', 'pharma', 'betting') and explaining that omitting the topic gives a cross-category spread. This helps the agent understand the parameter's usage.

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

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

The description uses multiple natural language queries to clearly state the tool's purpose as an onboarding entry point. It specifies the verb 'suggest questions' and the resource 'Pipeworx capabilities', and distinguishes itself from siblings like 'ask_pipeworx' and 'entity_profile' that serve different functions.

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

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

The description explicitly states when to use the tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also explains the optional topic parameter to narrow down categories. Although it doesn't explicitly say when not to use it, the guidance is clear and helpful.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), it explains the row is deactivated, not deleted, and that historical events remain available. Adds valuable behavioral context without contradiction.

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

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

Two sentences, 35 words, front-loaded with the action. Every sentence serves a purpose; no redundancy or waste.

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

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

For a simple one-parameter mutation with no output schema, the description covers ownership, deactivation behavior, and links to related tool. Complete and sufficient.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The tool description adds no new semantic details about the parameter beyond what the schema provides, meeting the baseline.

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

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

The description clearly states 'Cancel a subscription by id,' identifying the verb and resource. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' without ambiguity.

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 ownership enforcement: 'you can only cancel your own subscriptions,' providing a clear condition for when to use. Mentions deactivation and historical events via 'recent_alerts,' hinting at alternatives.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower. The description adds high-value behavioral context: distinct verdicts, 'could_not_verify' means the check did not happen and must not be treated as evidence, 'unsupported' means no source coverage, and verification_error fields. This goes well beyond annotations and clarifies important failure semantics. No contradiction with annotations.

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

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

The description is long but packed with necessary detail: usage, routing, return values, and caller caveats are all present. It is front-loaded with example phrasings and flows logically, though the density could overwhelm some agents. Each sentence adds value; minor redundancy in the pipeline description prevents a 5.

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

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

Given there is no output schema, the description fully compensates by enumerating the verdict values, the actual value with citation, reasoning, and the verification_error payload. It also clarifies the distinction between 'could_not_verify' and 'unsupported' — critical for correct caller behavior. The tool is complex, and this description covers all essential aspects, so a 5 is warranted.

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

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

Schema coverage is 100% and both params already have descriptions. The description adds extra meaning beyond the schema: it explains 'tolerance_pct' overrides the claim wording's implied tolerance, gives a concrete range (0.5–50), and suggests 'set 1–2 for hallucination detection'. This is useful guidance not present in the schema, justifying a 4.

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

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

The description clearly states a specific verb+resource: verifying natural-language claims against authoritative sources. It distinguishes from siblings by detailing the SEC EDGAR fast path and grounded fallback, and even notes it replaces a multi-step orchestration. Example phrasings ('fact check', 'verify the claim that…') make the tool's purpose unmistakable.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', providing a clear context. It also implies an alternative (replaces 4–6 sequential calls) and explains routing for company-financial vs. other claims, but lacks explicit when-not guidance or named sibling alternatives, stopping 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.