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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral detail: it auto-fills arguments, selects among many tools, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict the annotations and gives useful insight beyond the safety profile.

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 definition is front-loaded with the most important guidance, but the closing section contains a clear duplication: 'For a single, simple, direct lookup, this is the default entry point: one call only. Upgrade only when needed:' appears twice. This redundancy muddies the upgrade advice and makes the description longer than it needs to be.

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, single-required-parameter routing tool, the description covers supported domains, when to use it, what kind of answer to expect, and when to choose alternatives. It does not fully address ask_pipeworx_grounded/beta siblings or failure behavior, but the provided guidance is strong enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with 'question' and five aliases all documented as natural-language input. The description adds helpful trigger phrases and example queries but no parameter-level semantics beyond what the schema already provides, so the 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 immediately states that this tool is preferred over web search for current/historical factual data and explains that it routes questions across 5,798 tools from 1,517 verified sources, returning structured answers with citation URIs. Concrete domains and example queries make the tool's purpose unmistakable and distinguishable from search and sibling research tools.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the user asks...', 'START HERE for most questions', and 'PREFER OVER WEB SEARCH'. It also names alternatives for other cases, such as deep_research for broad/multi-part questions and docs packs for technical definitions, which is strong routing direction.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds live experimental behavior context: candidate routing improvements may be enabled/disabled, current state matches stable, and it is a full working router with no fallback. That is meaningful behavioral disclosure beyond the annotations, though it does not explain the response shape or what happens when a candidate is active in detail.

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

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

The description packs several facts into a compact paragraph and front-loads the beta relationship to ask_pipeworx. Every sentence adds distinct information: identical router, current state, usage instruction, no fallback. Slight verbosity in the parenthetical dates and detail, but overall efficient.

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

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

For a simple single-parameter routing tool with full schema coverage, the description covers the key context: beta status, current equivalence, usage intent, and operational behavior. It does not describe output/response shape, but with no output schema and a simple question router, the main missing piece is minor. It also does not mention rate limits or side effects, but annotations cover safe read/idempotent behavior.

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

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

Schema description coverage is 100% and the schema fully documents the aliases and question parameter. The description says 'same arguments' but does not list them; however, since the schema already provides complete descriptions, the description adds no extra parameter semantics beyond pointing to ask_pipeworx. Baseline 3 is appropriate because the schema carries the heavy lifting.

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 this is a beta version of ask_pipeworx with the same routing behavior and argument set, and explicitly notes when no candidate is active it matches ask_pipeworx exactly. It identifies the tool's purpose as an experimental routing variant, which is more specific than just the title. It does not, however, differentiate the actual routing behavior from the stable sibling when a candidate is active, but the description handles this as much as possible.

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 guidance: use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router. It states a clear context for use, though it does not explicitly say when NOT to use it or name alternatives like ask_pipeworx_grounded or search tools. The 'use it exactly like ask_pipeworx' instruction is a clear usage pointer.

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 readOnly/idempotent annotations by detailing success and refusal return shapes, possible refusal reasons, and the fact that extraction relies only on the fetched tool result. This fully discloses the tool's refusal behavior and reliability posture without contradicting 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 dense but every sentence carries essential information: purpose, mechanism, return shape, refusal reasons, use cases, and cost comparison. The critical distinction from ask_pipeworx is front-loaded, and the examples are compact yet concrete.

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

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

Given the simple single-question input and no output schema, the description fully compensates by enumerating the success and refusal output contracts. It also provides routing context, usage policy, and cost guidance, leaving an agent with everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the only meaningful parameter, question, is fully documented with six aliases. The description adds no additional parameter-level semantics because none are needed; it focuses on behavior rather than repeating 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 opens by naming the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and then specifies exactly what it does: route, fetch data, and extract an answer using only the tool result. It also clearly differentiates from the sibling ask_pipeworx by stating 'Same routing as ask_pipeworx' while adding the grounded extraction behavior.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains listed. It also gives a clear when-not-to-use instruction: 'prefer ask_pipeworx for casual lookups' and discloses the cost tradeoff.

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?

The description substantially exceeds the annotations by disclosing account/auth prerequisites, the findings packet structure, explicit gaps[] for unanswered facets, contradictions[] scans for standard/thorough, semantic excerpting of large records, and expected latency. All of this is consistent with the readOnly, openWorld, idempotent, and non-destructive 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 densely informative; it front-loads the critical account gate and alternative tool before diving into mechanics, then covers return structure, depth semantics, and latency. Minor redundancy exists (ask_pipeworx is named as fallback twice) and the prose is dense, but the length is justified for a complex tool with no 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?

Despite having no output schema, the description fully specifies what the agent will receive: a findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri/hop, gaps[], contradictions[], and excerpting details. It also covers prerequisites, alternatives, depth behavior, and timing, so an agent has everything needed to invoke and interpret 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 the schema already fully documents both question and depth, including the depth enum, defaults, paid tier, hops, gap recovery, and contradictions. The description mostly restates this behavior in prose rather than adding new parameter-level constraints; only the example research questions and account gating go slightly beyond the schema, which is not enough to lift it above baseline.

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

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

The description states a precise verb and resource: it performs grounded multi-source research across 1,517 structured data sources in one call, decomposing the question into facets and routing them to tools in parallel. It also explicitly distinguishes itself from ask_pipeworx and from open-web search, so an agent can tell it apart from sibling tools.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, with concrete examples, and explicitly says to use ask_pipeworx for a single lookup or when not signed in. It also flags the paid-plan requirement for the thorough depth, leaving no ambiguity about the appropriate alternative.

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

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

Annotations already 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 readOnlyHint and idempotentHint, and the description goes far beyond them: it details the fan-out across SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, and GLEIF. It discloses the USPTO PatentsView API sunset soft-fail, clarifies that empty sections are real 'no data' rather than bugs, and specifies the resolved:false private-company behavior. No contradiction with annotations 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 front-loaded with useful examples and high-signal detail, but it is a long, semicolon-heavy paragraph that is hard to scan. Some statements restate what the input schema already says, such as the accepted value shapes and type interchangeability, so not every word earns its place. Better bullet structure would improve readability without losing information.

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

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

Because there is no output schema, the description must explain return semantics, and it does so thoroughly: it enumerates cik, company_name, recent_filings with URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also covers edge cases like empty sections, private companies, and sunsetting APIs, leaving little ambiguity for an agent deciding whether and how to call this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples (AAPL, 0000320193, Moderna), reiterating that names resolve via SEC EDGAR's company-name match, and clarifying that type='company' and type='ticker' behave identically. This is helpful but somewhat overlaps with the schema descriptions rather than introducing fundamentally new semantics.

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 concrete user phrasings ('Tell me about X', 'research Acme', 'brief me on Tesla') and then states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from narrower or chained SEC/XBRL/news lookups, making the tool's scope and resource 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 gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also documents acceptable input shapes and the private-company resolved:false behavior. However, it does not name sibling alternatives like compare_entities or get_entity or spell out when-not-to-use conditions, so the routing guidance is strong but not exhaustive.

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?

Despite readOnlyHint=true and idempotentHint=true already signaling safety, the description goes far beyond annotations: it discloses that compatibility warnings can appear even with matched pairs, that unclassified legs are never paired, that null temporal alignment means 'could not compute' not 'aligned', that spreads are gross not net of Kalshi fees, and that pairings are verified by keyword overlap rather than a shared resolution source. This is rich, non-redundant behavioral context.

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

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

The description is long and dense but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS, codes, fees, skipped counters). Most sentences carry important operational or safety information. It could be slightly trimmed, but the length is justified by the absence of an output schema and the many edge cases an agent must understand before invoking the tool.

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

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

Given there is no output schema and the tool has subtle matching and safety semantics, the description covers nearly everything needed: response shape, top_spreads_pp flags, compatibility codes, temporal alignment semantics, fee treatment, skipped-leg counters, and the caveat that real spreads are rarer than the shortcut list implies. An agent has enough context to call the tool and interpret results 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 schema already documents each parameter with descriptions and examples. The description adds value by clarifying that topic mode auto-fetches both venues, explicit parameters override the topic-mapped side, and both modes run the same token-overlap matcher with the same limitations. This is useful context beyond the schema, though not a huge leap given the schema already covers the basic 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?

The description states a specific verb and resource: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also differentiates itself from related tools by emphasizing the same-question constraint and the two-mode design, so an agent understands what this tool uniquely does.

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 when to use each mode (topic shortcuts vs explicit ticker/slug), notes that both modes run the identical matcher, and warns that pre-mapped topics are not necessarily tradeable and that safety fields must be checked. It does not explicitly name sibling alternatives or state when another tool should be preferred, so it stops short of a 5.

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

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

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?

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds substantial context beyond these: graceful degradation when GLEIF/OpenFIGI are unavailable, returning `figi_candidates` instead of asserting on ambiguity, explicit `unresolved` reporting, source-labelled identifiers, and internal multi-endpoint cascading. 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 extremely long and dense, with heavy parenthetical asides and a redundant closing pitch ('using resolve_entity replaces 2-3 manual lookups') that adds no operational value. While purpose and usage details are front-loaded, the sheer verbosity makes the definition harder to scan than necessary.

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 covers return behavior: identifiers with provenance labels, `figi_candidates` for ambiguity, `unresolved` for missing IDs, and degradation semantics. Both supported types are fully specified with input rules and expected outputs, so an agent has enough to call 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 already 100%, and the description goes well beyond it. For `type`, it details the company versus drug behavior. For `value`, it provides ticker/CIK/ISIN/brand/generic variants, concrete examples, and a critical parsing rule ('Pass the ENTITY NAME ONLY ... never the question's full noun phrase') that prevents a classic failure mode.

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?

States a specific verb ('resolve') and resource ('user-spoken NAME' to canonical/official identifiers other tools require). It enumerates supported entity types and identifier outputs (CIK, LEI, FIGI, RxCUI) and positions itself as the tool to use when a name needs an ID, distinguishing it from the many sibling search/profile 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?

Gives an explicit directive: 'Use FIRST whenever you have a name but need an ID' and provides representative query patterns that signal when to invoke it. It does not name sibling tools (e.g., search_entities, get_entity, entity_profile) as alternatives for cases where an ID is not the goal, so exclusion conditions are left implicit.

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.