Reddit

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds transparency by clarifying the default model (Workers AI, free), the cost implication of using Anthropic (BYO key), and the return structure (per-model data + combined view). No contradictions.

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

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

The description is concise (3 sentences) yet packed with essential information: core function, parameters, return format, and use cases. No superfluous words.

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

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

Given the 4 parameters (1 required) and no output schema, the description provides sufficient context: explains return format, use cases, and parameter roles. The input schema's descriptions are also comprehensive, making the tool fully understandable.

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

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

Schema has 100% coverage with descriptions. The tool description adds context beyond the schema, such as the default model being free and the purpose of the _apiKey parameter, enhancing understanding of cost and 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 precisely states the tool probes LLMs for brand visibility and scores it (0-100) per model, with specific use cases like AI-marketing audits and competitive monitoring. It clearly distinguishes from sibling tools by its unique function.

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 (AI-marketing audits, pre-launch checks, competitive monitoring) and how to use optional parameters (apiKey for Anthropic, context for disambiguation). However, it does not explicitly state when not to use it or mention alternative tools.

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

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

The description discloses the tool's internal behavior beyond the annotations: it routes to thousands of tools, fills arguments on the user's behalf, returns structured answers, and includes stable citation URIs. It also states it is the default entry point and makes one fast call. These details add real context beyond readOnlyHint/openWorldHint/idempotentHint, and nothing in the description contradicts the annotations.

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

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

The description is well-organized into preference, behavior, usage, examples, and escalation, and the most important guidance is front-loaded. However, it is noticeably verbose, with redundancy between 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it', and the long list of examples and exact tool counts could be trimmed without losing meaning.

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

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

Given the tool's breadth, no output schema, and multiple alias parameters, the description is mostly complete: it explains what the tool returns, when to use it, how to phrase inputs, and when to use alternatives. It could be more complete by describing the exact response shape or failure behavior, but the core context an agent needs to invoke it correctly is present.

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

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

With 100% schema description coverage, the schema already documents all six parameters as aliases for the question field. The description adds value by giving concrete example queries ('current US unemployment rate', 'Apple's latest 10-K', 'adverse events for ozempic') and clarifying that the input is any factual natural-language question. This is more than the baseline, though not parameter-level syntax guidance.

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

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

The description clearly identifies ask_pipeworx as a question-routing and answering tool: it 'Routes the question to the right one of 5,798 tools' and 'returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default starting point, so the agent can tell it apart without opening other schemas.

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: prefer over web search for factual/current/historical data, use for 'what is', 'look up', 'find', 'get the latest', and similar queries, and start here for most questions. It also provides clear escalation rules, naming ask_pipeworx_grounded for exact-match single-source needs and deep_research for broad/multi-part questions, with concrete examples throughout.

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, and idempotent safety. The description adds that this is a live experimental router with candidate improvements enabled whenever one is under test, that no candidate is currently active, and that it is a full working router with no fallback. This is useful behavioral context beyond the annotations, though it doesn't detail how routing might differ when a candidate is active.

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 and front-loads the beta identity, then explains current state and usage. It is slightly dense (5,798 tools, dates) but each sentence earns its place by clarifying the experimental nature and current equivalence to the stable router.

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 is a simple question-as-router with a single required parameter and no output schema, the description covers what an agent needs: what it is, how to use it, and the fact that it currently matches the stable router. It relies on cross-referencing ask_pipeworx for response shape, but that is an acceptable shortcut for a beta variant.

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 all six parameters and their aliases. The description only references 'same arguments' as ask_pipeworx without adding semantic detail beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: a beta version of ask_pipeworx, a universal router with the same 5,798 tools and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge, so an agent can tell it apart from siblings without opening the schema.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router to decide merges. This gives a clear when-to-use condition and implies the stable alternative, so an agent knows the selection criteria.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral context beyond that: the refusal contract with exact refusal_reason values, the evidence extraction guarantee using verbatim quotes, and the 'one extra LLM call' cost. 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 dense but every sentence earns its place: routing, grounding behavior, return shape, refusal reasons, use cases, and cost tradeoff. It is slightly long and not broken into paragraphs, but the complexity of the tool justifies the length.

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

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

Despite no output schema, the description fully documents the success return object, the refusal object with enumerated reasons, use-case constraints, and the sibling relationship. For an agent deciding between ask_pipeworx variants, nothing essential is missing.

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

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

Schema description coverage is 100%, with all six properties documented as aliases for 'question.' The description adds no parameter-specific detail, but the schema fully explains the singular input, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads', and explains it routes like ask_pipeworx but then 'EXTRACTS the answer using ONLY what the tool result contains.' This clearly distinguishes it from the sibling ask_pipeworx by its grounded, evidence-based 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 explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and when not to: 'prefer ask_pipeworx for casual lookups.' It also names the alternative and explains the extra cost tradeoff, leaving no doubt about selection.

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

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

The description far exceeds what annotations provide. It details internal fan-out logic, resolver contract with confidence levels, parent-event extraction, news fallback mechanisms, safety short-circuits, and cancellation-rule parsing. All behavioral traits are disclosed with concrete examples and edge-case handling.

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

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

The description is lengthy but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The first sentence front-loads the core purpose. While dense, every sentence adds value for a complex tool.

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

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

Despite having no output schema, the description thoroughly explains all response fields: market stats, analysis metrics (model probability, edge, kelly), evidence sources, resolver confidence, parent event details, news fallback fields, and tradeability warnings. It also covers multiple classification scenarios and edge cases.

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 tool description adds minimal new information beyond the schema: it mentions 'quick' and 'thorough' depth values which are already in the schema enum. The description does not expand on the meaning of parameters beyond what the schema provides.

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

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

The description starts with a clear verb-resource pair ('Research a Polymarket bet') and specifies the exact inputs (slug, URL, question text). It distinguishes its purpose from sibling tools like polymarket_arbitrage and polymarket_edges by stating specific use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'.

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 provides use cases and advises when to use the tool. It also explains blocking conditions (low-confidence matches, closed markets, wide spreads) that affect tool behavior. However, it does not explicitly state when NOT to use it or compare directly to alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive traits. The description adds substantial behavioral context: exact data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is a single dense paragraph but front-loads the core purpose and example phrases. Every sentence adds value (use cases, type-specific behavior, sorting, alternatives). Could be slightly improved with bullet lists for clarity, but remains highly efficient.

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

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

Given the tool's modest complexity (2 params, no output schema), the description covers all essential aspects: when to use, what data is returned for each type, sorting, citation URIs, and data source details. The agent can confidently invoke this tool without additional context.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning beyond the schema: it provides example inputs (e.g., 'AAPL', 'MSFT'), specifies min/max items, explains that values depend on type (tickers vs drug names), and describes how results are sorted. 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 function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It provides concrete example phrases (e.g., 'Compare X and Y', 'which is bigger') and clearly distinguishes it from sibling tools like entity_profile by emphasizing it replaces multiple sequential lookups.

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

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

The description gives clear when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It explains the data returned for each entity type and sorting behavior. However, it does not explicitly state when NOT to use the tool or name specific alternatives (beyond the implicit single-entity lookups).

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

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

The annotations already signal read-only, open-world, idempotent, and non-destructive behavior, and the description adds valuable context beyond those hints: account and paid-tier requirements, 15-90s latency, parallel decomposition, gap-recovery behavior, contradictions[] results, fetchable citation URIs, and semantic excerpting. Nothing in the description contradicts 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 and front-loaded with the most critical routing constraint, but it is a single long paragraph with heavy parenthetical flourishes and repeated depth-level details that already appear in the schema. Most sentences earn their place, but the structure could be clearer and more concise.

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

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

There is no output schema, so the description carries the burden of explaining return behavior. It covers the findings packet, verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], latency, auth prerequisites, and fallback tool. For a tool with this complexity, the description is unusually 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 the input schema already documents both 'question' and 'depth' thoroughly, including enum meanings. The description adds useful illustrative examples and clarifies the relationship between depth and iterative hops, but it does not need to compensate for missing parameter documentation. 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 names the specific verb and resource: 'grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call. It explicitly differentiates itself from open-web search and from ask_pipeworx, and clarifies it is for broad/multi-part questions rather than single lookups. This gives an agent a precise, distinguishing 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?

It gives explicit when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx.' It also states the tool is 'Best for broad/multi-part questions over structured data,' which structurally separates it from sibling tools.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true. The description adds transparency about return format (top-N, ready-to-call results) and no second lookup needed, which goes beyond basics.

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 examples, but slightly long. Every sentence adds value, though some redundancy (list of domains could be shortened).

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 clearly states what the tool returns (names, descriptions, schemas), which is sufficient for a discovery tool. Context is complete.

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

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

Schema coverage is 100%, and the description adds meaning by explaining 'query' with natural language examples and listing aliases (task, q, search, description), clarifying flexibility.

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

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

The description uses a specific verb ('Find tools') and resource ('tools'), lists many domains (SEC filings, FDA drugs, etc.), and distinguishes from sibling search tools by being a meta-tool for tool discovery.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set', providing clear usage context. Lacks explicit when-not or alternatives, but the context is sufficient.

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

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

Goes well beyond the readOnlyHint/idempotentHint annotations. It discloses the fan-out across SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, GDELT→GNews, and GLEIF; soft-fails for patents; empty sections meaning 'no data, not a bug'; sources_used/sources_failed; and the resolved:false behavior for private companies. No contradiction with annotations.

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

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

The description is long, but every clause earns its place by enumerating return sections, source behaviors, and failure modes that would otherwise be unknown given no output schema. It is front-loaded with purpose and examples, though it could benefit from more structured formatting.

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

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

With no output schema, the description carries the full burden of return-value documentation. It lists every expected section (cik, company_name, recent_filings with URIs, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/failed) and covers input edge cases and failure semantics. Nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by reinforcing that 'type' is interchangeable and that 'value' can be ticker, CIK, or name, plus the resolution/failure behavior. It exceeds baseline by tying parameters to real-world edge cases like private-company resolution.

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 explicit user-intent examples and immediately states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chaining single-pack lookups and from sibling tools by emphasizing the holistic, cross-source scope, so an agent can confidently select it.

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

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

Provides an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies accepted input forms and the private-company resolved:false path. It does not name sibling tools like resolve_entity or deep_research explicitly, but gives enough routing 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 destructiveHint=true. Description confirms deletion and adds usage context (clearing stale/sensitive data). No contradiction, but no additional behavior beyond annotations.

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

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

Two efficient sentences: first defines action, second provides usage guidance. Zero wasted words.

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

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

For a single-parameter, no-output-schema tool, description covers purpose, usage, and behavior sufficiently.

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?

Single parameter 'key' is fully described in schema (100% coverage). Description does not add extra meaning, meeting baseline adequacy.

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 'Delete a previously stored memory by key.' Specific verb (delete) and resource (memory) with direct contrast to siblings 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 says 'Use when context is stale, the task is done, or you want to clear sensitive data.' Provides clear context and alternatives via sibling 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=true, idempotentHint=true, destructiveHint=false. Description adds details about the process (fetches page, extracts title/description/links, emits standard markdown) and output format (single text blob for site-root/llms.txt), which is useful beyond annotations.

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

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

The description is concise with three sentences: purpose, process, use cases. Front-loaded with the main action, no redundant 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 2 simple parameters and no output schema, the description explains the output format and use cases, making it fully complete for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100%, with both parameters (url, max_links) described. Description does not add any new information beyond what is in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Generate', the resource 'llms.txt file', and the scope 'for any URL'. It distinguishes this tool from siblings as no other sibling tool generates llms.txt files.

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 use cases: getting a client's site indexed, drafting for your own project, auditing a competitor's AI crawlability. It does not mention when not to use, but given the unique functionality, it's clear enough.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds transparency by specifying the returned fields (title, author, body, permalink, and comment threads with author, body, date) and disclosing the limitation about vote scores not being available via Reddit RSS, which is useful context beyond annotations.

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

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

Two sentences, front-loaded with the core action. The first sentence states what it does and returns; the second adds a relevant limitation. No wasted words.

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

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

For a simple get-by-ID tool with strong annotations and an output schema, the description covers the purpose, return structure, and a key limitation. It's sufficient for an agent to select and invoke the tool correctly in most contexts.

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 provides full coverage of the single parameter post_id with type and example. The description restates the parameter's role ('by post ID') but doesn't add new semantic details beyond what the schema already provides, so a baseline of 3 applies.

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

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

The description uses a specific verb 'Get' and identifies the resource as 'a Reddit post and its comments' by post ID. It distinguishes from siblings like get_subreddit and search_posts by focusing on a single post and its comment threads.

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 when you have a specific post ID and need the post plus comments. It notes the limitation that vote scores aren't available, which signals a situation where this tool is insufficient, but it doesn't explicitly name alternative tools or provide when-not-to-use guidance.

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

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

Annotations declare readOnly, idempotent, non-destructive, which the description aligns with. Adds behavioral context: sort options, time window requirement, return fields, and the limitation that vote scores/comment counts are unavailable via RSS.

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

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

Five sentences, front-loaded with purpose, followed by usage guidance, options, output, and limitation. No filler or redundancy.

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

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

Covers core behavior, parameters' semantics, output fields, and a key limitation. With output schema present and annotations, the description is fully adequate.

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

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

Schema already documents all four parameters with descriptions (100% coverage). Description adds real-world examples and clarifies that 'time' only applies to top/controversial sorts, adding value beyond schema.

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

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

Clearly states 'Get posts from a REDDIT subreddit' with specific examples. Distinguishes from sibling tools like get_post by emphasizing subreddit-level queries and preference for 'what are people posting in r/<sub>'.

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 'PREFER for' with concrete query phrasings, establishing when to use this tool. It does not name alternative tools for when not to use, but the preference list is clear enough.

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=true, idempotent=true, destructive=false. The description adds context about returning active subscriptions, the optional include_inactive parameter, and the list of returned fields, which provides behavioral insight beyond annotations.

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

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

Two sentences, front-loaded with the primary action, and no wasted words. Every sentence adds value.

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

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

The tool is simple with one optional parameter. The description explains the return fields and use cases. It lacks mention of pagination or ordering, but that is likely not needed for 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 coverage is 100% with a single boolean parameter fully described. The description does not add additional meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and specifies the returned fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing, but does not explicitly differentiate from other list tools.

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

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

The description provides explicit context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides appropriate usage, though it does not mention when not to use or 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?

While annotations are all false (providing little signal), the description adds rich behavioral context: rate-limiting ('Rate-limited to 5 per identifier per day'), cost/free status, token-based follow-up ('Filing without an account returns a claim_token'), and team cadence ('reads digests daily and signal directly affects roadmap'). This far exceeds what annotations provide.

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

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

The description is dense but every sentence carries essential information: purpose, conditions, exclusions, token flow, team process, rate limits. It is front-loaded with the core purpose, and each subsequent sentence earns its place 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?

The description fully covers the tool's usage model, including edge cases like cross-server feedback, token-based status checks, and rate limits. It completes the schema and annotations by explaining the overall flow and expected outcomes, making it self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining claim_token mechanics, describing how to frame feedback ('in terms of Pipeworx tools/packs'), and clarifying what to avoid in the message ('don't paste the end-user's prompt'). This provides guidance beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and distinguishes itself from siblings like ask_pipeworx by focusing on feedback rather than questions.

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

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

Explicitly provides when to use ('when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well') and when not to use ('ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead'). This is clear, actionable guidance with 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 indicate read-only, idempotent, non-destructive. Description adds valuable context: self-aggregating, no PII, cached 5min-1h. No contradictions.

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

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

Well-structured with bullet points for use cases. Front-loaded main purpose. Could trim some wordiness but remains clear and efficient.

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

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

No output schema, but description explains return types (top tools, packs, total call volume) and caching behavior. Adequately complete for a simple read tool.

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

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

Only one parameter (window) with full schema coverage. Description adds meaning: 'shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Clearly states it returns top tools, top packs, and total call volume over recent windows. Distinguishes from sibling tools like ask_pipeworx and discover_tools by focusing on popularity metrics.

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?

Lists three explicit use cases (discovering hot data sources, confirming popular tool, aligning use case). Doesn't name alternatives but context makes clear when not to use (e.g., for direct queries).

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

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

Description adds extensive behavioral context beyond annotations: details monotonicity checks, partition sum logic, semantic anchor, partition filter, fill check, and response structure. No contradiction with annotations.

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

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

Front-loaded with purpose, but the description is verbose with detailed algorithm explanations (e.g., semantic anchor, partition filter). Could be tightened slightly without losing essential guidance.

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 specifies the return structure (opportunities array, partition_check fields, fill check details) and covers all use cases for the two optional parameters.

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

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

Both parameters are described in the schema (100% coverage), and the description enriches them with usage examples, mode behavior, and slug/URL acceptance, adding significant meaning beyond schema types.

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

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

Description explicitly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It clearly distinguishes the three modes (no args, event, topic) and explains what each does, making the 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?

Provides explicit guidance: 'Call with NO args for a trending_scan', recommends 'event' for specific markets, and explains when to use 'topic' for cross-event scanning. Also advises when not to trade based on fill check results.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: caching behavior (KV-level, 1 hour, keyed on knobs), detailed edge calculation methods (lognormal barrier, GDELT momentum, partition overround with bias correction), slippage handling, tradeable-edge filters, and diagnostic output. 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 long but well-structured with clear sections and bullet-point-like formatting. It front-loads the purpose and segments. Some redundancy exists (e.g., repeating 'FIVE MODEL FAMILIES' and later listing them), but overall it earns its length given the tool's complexity.

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

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

Given the tool's complexity (9 parameters, multiple model families, diagnostics, caching), the description is remarkably complete. It explains why Fed bets are excluded, how each segment works, edge calculation details, filter knobs, and diagnostic output. No significant gaps are apparent.

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 does not add much beyond what's already in the schema for each parameter; it primarily repeats or slightly elaborates on properties like min_liquidity and max_spread_pp as 'tradeable-edge filters'. The additional context is minimal but non-zero.

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 (scan, return) and resource (Polymarket markets) with a specific purpose (opportunities where Pipeworx data disagrees with market price). It also provides a user goal ('what should I bet on today') and distinguishes itself from siblings like polymarket_arbitrage by focusing on Pipeworx data and edge calculation.

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

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

The description gives clear context for when to use the tool ('what should I bet on today', discover without paging). It does not explicitly state when not to use it or provide direct comparisons to alternatives like polymarket_edge_tracker, but the context is strong enough for an agent to infer appropriateness.

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 rich behavioral detail: it reads from daily snapshots, provides time-series data, trend analysis, decay rates, and limitations (60-day TTL, not intraday). No contradiction.

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

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

The description is front-loaded with purpose, then explains args and response structure. It is informative but somewhat verbose in the response section, which could be trimmed. Still, it avoids wasteful 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 no output schema, the description thoroughly explains return structure (tracked[], expired[], snapshot_dates[]) with field details, plus limitations and assumptions. It is complete enough for an agent to use without guesswork.

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 reinforces default values and constraints (days max 30) beyond the schema, adding value. However, the schema already conveys core 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 clearly states it provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It distinguishes from sibling 'polymarket_edges' by focusing on time-series analysis rather than single snapshots.

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 analyzing edge persistence and decay over time, contrasting with looking at a single edge. However, it does not explicitly state when not to use it or directly name alternatives among siblings.

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

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

Adds detailed behavioral context beyond annotations: walks order book ladder, returns specific fields (top_of_book, vwap, slippage, verdict, etc.), and explains risks like thin legs and forced directional risk. No contradiction with readOnlyHint, destructiveHint, idempotentHint.

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

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

Description is substantial but well-organized with sections and bullet-like lists. Every sentence adds value, though it could be slightly more concise. Front-loaded with 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 no output schema, the description fully explains return values for both modes, including edge cases like thin legs and partial fills. Covers all necessary context for an agent to use the tool correctly.

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

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

Schema has 100% coverage, but description enhances understanding by explaining parameter roles in different modes, defaults, and interactions (e.g., side default logic, size_usd interpretation). Adds moderate value over schema.

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

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

Clearly defines the tool as a realizable-vs-theoretical edge check against live order-book depth, with explicit single-market and basket modes. Distinguishes itself from siblings by stating use before polymarket_arbitrage signals or large trades.

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: before acting on polymarket_arbitrage signals or trades above ~$500. Warns about partial basket fills converting arb to unhedged position, providing clear context for usage.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: keyword overlap matching, fee-schedule omission, null temporal-alignment semantics, unclassified legs never being paired, and compatibility codes. This goes well beyond the annotations and clearly explains what the tool does and does not guarantee.

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?

Although long, the description is densely packed and well structured: purpose, modes, response shape, safety fields, compatibility codes, and fee caveats are all clearly separated. Every sentence contributes operational information, and the core purpose is front-loaded.

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

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

With no output schema and three optional parameters, the description carries full responsibility for interpreting results. It explains leg-by-leg prices, spread direction, compatibility codes, temporal alignment behavior, skipped counts, and the gross-vs-net fee caveat. An agent has enough to call and interpret this 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 baseline is 3. The description adds meaningful value by enumerating the 10 accepted topic values and by clarifying that explicit ticker/slug parameters override the topic-mapped sides. This gives agents more confidence 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 a specific verb and resource: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It differentiates itself by venue pair and by the two modes, but it does not explicitly name sibling tools like polymarket_arbitrage, so sibling differentiation is implicit rather than explicit.

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 two modes are well explained: pre-mapped `topic` shortcuts for quick use and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. The description also warns that pre-mapped topics often are not tradeable, but it does not explicitly contrast this tool with sibling alternatives or say when to prefer them.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already declare safe read behavior. Description adds valuable context: listing all keys when key is omitted, scoping by identifier, and pairing with forget for deletion.

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, zero waste. Front-loaded with purpose ('Retrieve a value...'). Every sentence adds independent 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 annotations cover safety and description covers retrieval, listing, scoping, and sibling pairing, plus no output schema needed for a simple read, the description is fully adequate.

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

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

Schema has 100% coverage with description for 'key'. Description adds the critical behavior: omitting key lists all keys. This enriches meaning beyond schema alone, meriting a 4.

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

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

Description uses specific verb 'Retrieve' and resource 'value previously saved via remember', and explicitly distinguishes from siblings like 'forget' and 'remember'. It clearly states both retrieval and listing capabilities.

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?

Describes when to use: to look up context stored earlier without re-deriving. Mentions scoping and pairing with remember/forget. Lacks explicit 'when not to use' but provides clear 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=true, idempotentHint=true, and destructiveHint=false, but the description adds valuable context: the returned payload structure, the effect of setting `mark_read` (flags events read so next call shows newer ones), and that polls work fine. No contradiction with annotations.

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

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

The description is a single, concise paragraph of about 5 sentences. It front-loads the purpose, then details parameters and behavior, and ends with an alternative endpoint. 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?

Given the tool has 5 optional parameters, no output schema, and rich annotations, the description covers all necessary aspects: purpose, parameter usage, behavioral side-effects, and alternative access. It is complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for `mark_read` and `unread_only` (flags returned events read, returns only unread), but the schema already documents all parameters and their types/ranges. The description does not significantly extend understanding beyond the schema.

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

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

The description clearly states it pulls fired events from the subscription feed and returns the most recent alerts, specifying key fields (source, citation_uri, raw event payload). It distinguishes itself from siblings by focusing on the alert feed, which is unique among the listed sibling tools.

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

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

The description provides explicit guidance on when to use the tool (to retrieve alerts with optional filters) and mentions an alternative endpoint for scripts/dashboards, helping agents choose the right access method. It also explains the behavior of `mark_read` and notes that polling works fine.

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, etc.), the description details parallel calling, fan-out to multiple sources, GDELT→GNews fallback, soft-failure for patents due to API sunset, and return format with citations.

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 example queries first, then purpose, then detailed behavior. Every sentence adds value, and it is front-loaded with the most important 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?

Despite no output schema, the description explains the return structure (changes grouped by source, total_changes count, citation URIs) and covers fallback behavior and upcoming API changes.

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 even more context: typical value for 'since' (e.g., '30d'), only 'company' for 'type', and explanation of ticker vs CIK for 'value'.

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

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

The description clearly states the tool provides a change feed for a company, covering SEC filings, news, and patents, with example queries like 'What's new with X'. It explicitly distinguishes from sibling tool 'entity_profile' for static profiles.

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

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

The description includes explicit when-to-use examples and directs agents to use 'entity_profile' for static profiles, providing clear context for selection.

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

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

Annotations indicate non-destructive, idempotent write. Description adds crucial details: 24-hour retention for anonymous sessions, persistent for authenticated users, and scoping by identifier.

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 main purpose, no fluff. 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?

Complete for a simple key-value store: explains persistence, pairing, and scope. No output schema needed.

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

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

Schema covers 100% with clear descriptions. Description adds example keys and value as 'any text', but does not go significantly beyond what schema provides.

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

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

Clearly states 'Save data the agent will need to reuse later' and explicitly pairs with recall and forget, distinguishing it from sibling tools like recall and forget.

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

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

Provides explicit usage context ('when you discover something worth carrying forward') with examples, and mentions pairing with recall and forget, though no explicit when-not-to-use.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral nuance: ambiguous matches return figi_candidates rather than asserting, unresolved identifiers are explicitly listed under 'unresolved', and GLEIF/OpenFIGI enrichment degrades gracefully while EDGAR identifiers still return. This is strong transparency 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 long and dense with nested parentheticals, but the complexity of the tool justifies most of it. It is front-loaded with user intents and the core purpose. There is some repetition between 'cascades through several lookup endpoints' and 'replaces 2-3 manual lookups,' so it is slightly heavier than strictly 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?

With no output schema, the description compensates well by covering key return behaviors: source-labeled identifiers, figi_candidates for ambiguity, an unresolved list, RxCUI citation links, and LEI ownership information. For a two-parameter tool with this level of internal complexity, the description is complete enough for an agent to call 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 coverage is 100%, but the description goes much further: it documents accepted input formats for value (ticker, CIK, ISIN, company name, brand/generic), gives an ISIN-to-LEI example, and warns against including trailing security-class words for bond issuer names. The enum semantics for 'company' and 'drug' are also substantially enriched.

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

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

The description opens with a precise operation: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the supported entity types and positions the tool as an identifier-resolution step, which distinguishes it from research or profile-oriented siblings.

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

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

It gives an explicit directive: 'Use FIRST whenever you have a name but need an ID,' plus concrete query-pattern examples and a note that it 'replaces 2-3 manual lookups.' It does not name alternatives or state exclusions, but the usage 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score, confidence, signal density per entity. It does not contradict annotations and adds behavioral details beyond them.

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

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

The description is three sentences, front-loading the core action and key details. Every sentence provides necessary information without redundancy.

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

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

No output schema exists, so the description covers the return format (ranked list with score, confidence, signal density). Parameter semantics and usage context are adequately addressed. Minor gap: does not mention maximum number of entities or any error conditions.

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% (4 parameters described), so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' for narrative and the rest as competitors, which is not in the schema. It also clarifies that _apiKey is optional only if 'anthropic' is in models.

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 compares AI visibility across multiple entities, ranks them, and identifies the most/least recognized. It uses a specific verb ('Compare') and resource ('AI visibility across entities'), and distinguishes itself from sibling tool 'ai_visibility_check' which is for single 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 explicitly says it is useful for competitive AI-marketing audits and gives a concrete example question. While it implies when to use, it does not explicitly state when not to use or directly mention alternatives beyond the sibling 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 safe, idempotent, read-only. Description adds that it fans out to two services, explains partial failure (sources_failed) and a timing caveat (bundlephobia first measurement 5-30s). 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?

Single paragraph but well-organized: starts with purpose, usage, output details, then limitations. Slightly dense but not verbose; could be slightly more structured with bullet points but still effective.

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

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

For a composite tool with no output schema, description covers input, output structure, behavior, fallbacks, and ecosystem limitations. An agent has sufficient information to invoke 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% with descriptions for both parameters (package and version). Description adds context: scoped packages accepted, version defaults to latest. Provides value beyond schema but schema already covers basics.

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

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

Description clearly states it's a composite check for npm packages, listing specific data aggregated (license, advisories, bundle size, etc.). Differentiates from siblings by noting NPM-only in v1 and directing other ecosystems to 'deps.dev:version'.

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

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

Explicitly says 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also mentions NPM-only limitation and alternative for other ecosystems, providing clear when-to-use and when-not.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description only needs to add behavioral detail. It does so by listing sort options, the default sort, and the exact returned fields, giving the agent useful expectations beyond the annotation flags. 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 consists of three short, front-loaded sentences covering the core action, scope, sort behavior, and return fields. There is no filler or redundant wording.

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 read-only annotations, complete schema coverage, and the presence of an output schema, the description provides enough context for an agent to invoke the tool correctly. It explains scope and sort behavior, while details like default limit and max are already captured in the 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%, so the description does not need to define each parameter. It adds a small amount of semantic value by clarifying 'across all subreddits' as the default and showing the 'search r/<sub> for X' usage pattern, but it largely restates what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Search Reddit posts by keyword' and immediately differentiates scope (all subreddits or one via the subreddit argument). It clearly distinguishes from sibling tools like get_post and get_subreddit by focusing on keyword-based search across posts.

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

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

The description provides clear context for when to use the tool: keyword-based search, optionally scoped to a single subreddit. It does not explicitly name alternatives or exclusions, but the search-vs-fetch distinction is strongly implied by the stated purpose and 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 mark the tool as read-only and idempotent. The description adds meaningful behavioral details: embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), similarity metric (cosine), input cap (200K chars), and truncation flagging. This adds strong transparency beyond annotations.

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

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

Four well-structured sentences that front-load the core purpose, then describe usage, pairing, and technical details. No wasted words—every sentence adds essential information.

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

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

Despite lacking an output schema, the description explains the return format (passages with offsets and scores), input constraints (cap and truncation), and integration with a sibling tool. This fully equips an AI agent to use 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 description coverage is 100%, so baseline is 3. The description provides examples for the query parameter and explains the limit as 'top-N passages', but does not add significant meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It specifies the inputs (text and query), outputs (top-N passages with character offsets and similarity scores), and distinguishes from siblings by mentioning its partner tool 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 advises when to use ('Use when the record is too big to cram into the prompt') and provides an alternative workflow pairing with ask_pipeworx_grounded. It also notes the character cap and truncation behavior, giving clear usage boundaries.

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

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

The description adds significant behavioral context beyond annotations: it notes the OAuth requirement, that subscriptions are persistent, the return of a new ID, and details on delivery channels with rate limits and verification. It does not contradict any annotations.

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

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

The description is front-loaded with the main purpose but becomes verbose with examples and delivery details. It could be more concise while retaining clarity. However, the structure is logical.

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 with nested parameters and no output schema, the description covers authentication, supported types, parameter details, delivery channels, constraints, and return value. It is thorough and leaves no obvious 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?

Although schema coverage is 100%, the description adds meaningful context by providing specific examples and syntax for each parameter, such as sec_8k requiring a ticker and optional items, and explaining the delivery object constraints. It also clarifies the return value.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like unsubscribe and list_subscriptions by focusing on creation, and provides specific examples of supported types.

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

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

The description explicitly states when to use (proactive monitoring) and provides authentication prerequisites (Pipeworx OAuth account). It mentions that anonymous and BYO accounts cannot persist subscriptions, and outlines constraints like SMS caps and phone verification. However, it lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true, destructive=false, so safety is clear. The description adds behavioral value by explaining that the tool returns example questions with exact tool+argument shapes drawn from a live catalog, and that calling with no arguments gives a full cross-category spread. 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 somewhat long but well-structured, starting with a summary of what the tool does, then listing example topics and usage patterns. Every sentence contributes value, though a slight rewrite could tighten the list of examples.

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

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

Given no output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool+argument shapes) and when to use it (onboarding, learning meta-tools). It covers both argument scenarios (full spread vs. focused topic) and is complete for a discovery tool.

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

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

Schema coverage is 100% with one optional parameter described. The description adds meaning by listing the possible topic values ('finance', 'pharma', etc.) and explicitly stating that omitting topic gives a cross-category spread, which clarifies usage 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 returns category-bucketed example questions for various topics, positioning it as the onboarding entry point. It uses specific verbs ('returns', 'call', 'use') and distinguishes from siblings by directing the agent to use this tool first before other meta-tools like ask_pipeworx.

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

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

Explicitly instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on when to pass no arguments vs. a specific topic. Names alternative tools (ask_pipeworx, entity_profile, etc.) as things to learn about through this tool.

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

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

Describes deactivation instead of deletion, ownership enforcement, and availability of historical events via recent_alerts. Adds value beyond annotations.

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

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

Two sentences, front-loaded with core action, no wasted words.

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

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

For a one-param tool with no output schema, description covers outcome, constraints, and side effects completely.

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

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

Schema has full coverage for the single param (id). Description adds context that id is the subscription id and ownership is enforced, exceeding schema description.

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

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

Clearly states action (cancel subscription) and resource (by id). Distinguishes from siblings like subscribe, list_subscriptions, and recent_alerts.

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

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

Explicitly mentions ownership enforcement and that historical events remain via recent_alerts, implicitly guiding when to use recent_alerts instead. No explicit when-not-to-use but sufficient for a simple tool.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals critical behavioral nuances: could_not_verify means the check did not happen and must not be shown as evidence, unsupported means no source was found, and the return payload (verdict, actual value with citation, reasoning). It also explains the automated routing between structured and grounded pipelines, adding needed 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 efficiently structured: trigger phrases, usage directive, routing logic, return values, and an 'IMPORTANT for callers' warning. Every sentence serves a purpose, and the special note about could_not_verify prevents misinterpretation. Though lengthy, it is densely informative with no 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 no output schema, the description fully explains the return values (verdict list, actual value with citation, reasoning) and distinguishes error modes (could_not_verify vs unsupported). It covers routing, coverage, and failure semantics, making it complete for callers to anticipate 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%, so the baseline is 3. The description does not significantly add meaning beyond the schema; for example, tolerance_pct's behavior ('Overrides the tolerance implied by the claim wording', 'set 1–2 for hallucination detection') is already fully detailed in the schema. The description's mention of 'exact percent-delta math' is more about tool behavior than parameter 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 begins with explicit natural-language trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states 'natural-language claim verification against authoritative sources'. It clearly distinguishes from siblings by describing a two-path system (SEC EDGAR for company-financial claims, grounded pipeline for all else) and notes it replaces 4–6 sequential calls, making it the single tool for claim verification.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and further explains the routing logic for claim types. However, it does not name alternative tools or provide 'when not to use' guidance, so it falls short of the explicit exclusion/alternative criteria.

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