Banking Regulations

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the default model is free and that using the Anthropic model requires a BYO key with direct payment, which is behavioral context not covered by annotations. 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 a single paragraph of four sentences, front-loaded with the main action and output. Every sentence adds value without fluff.

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

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

Given the tool has 4 parameters (1 required), no output schema, and annotations providing safety hints, the description covers the return structure (per-model object + combined view), use cases, and cost details. It is complete and 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 description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the default model for the 'models' parameter and the cost implication of '_apiKey'. This extra context justifies a score above baseline.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). The verb 'probe' and resource 'LLMs' are specific, and the output is explicitly described. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on generic visibility scoring rather than competitor-specific scanning.

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 on when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how to use it (default model free, optional paid model with _apiKey). However, it does not explicitly mention when not to use it or compare to alternatives among siblings, missing some exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral detail: the tool is a router that fills downstream arguments and returns structured answers with stable pipeworx:// citation URIs. This goes beyond the annotations and helps the agent interpret the output. No contradiction found.

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 substantially redundant: the 'Use whenever...' trigger list, the example set, and 'START HERE for most questions' are repeated, and the domain list is very long. While the core message is front-loaded, the duplication makes it bloated and less efficient than it should be.

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

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

For a tool with one required parameter and no output schema, the description is largely complete: it covers what the tool does, when to use it, domain coverage, input style, and the output contract (structured answer with pipeworx:// citation URIs). It does not address failure modes, fallback behavior, or when to choose a sibling tool, but these are moderate gaps.

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

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

Schema coverage is 100%: all six properties are documented, with the primary 'question' parameter described as a natural-language request and the others as aliases. The description adds representative example questions and clarifies it accepts natural language, but it does not materially extend parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description states a clear verb and resource: it routes questions to the appropriate tool among 5,798 tools across 1,517 verified sources, fills arguments, and returns cited answers. It also explicitly positions itself against web search. However, it does not differentiate itself from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, so it misses the highest bar.

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 strong selection guidance: prefer over web search for factual, current, or historical questions, and use whenever the user uses cues like 'what is', 'look up', 'find', or 'current'. It even says to use it when web search could also answer, with concrete examples. It does not mention sibling alternatives or explicit non-use cases, so it is not a perfect 5.

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

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

Annotations already declare readOnly/openWorld/idempotent safety, and the description adds genuinely valuable behavioral context beyond that: the beta/evaluation nature, that results are compared against the stable router to decide merges, that no candidate is currently active (with retirement date), and the crucial clarification 'Falls back to nothing — this IS a full working router.' No contradiction with annotations.

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

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

Four dense sentences, each earning its place: beta identity, identical scope, current activation state, usage instruction, evaluation purpose, and fallback clarification. It is longer than minimal but every sentence adds distinct information, and the beta framing 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?

Despite no output schema, the description covers the key facts an agent needs: what the tool routes, how it relates to the stable version, the current live state, when to choose it, and that the response shape matches ask_pipeworx. It also addresses the likely misconception that a beta might be degraded by stating it is a fully working router.

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 six parameters (question plus five aliases), so the schema already fully documents parameters; baseline 3 applies. The description only references 'same arguments' as ask_pipeworx, which does not add parameter-level meaning, but none is needed given complete schema coverage.

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

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

The description states a specific function: it is a universal router ('same 5,798 tools, same arguments, same response shape') that answers questions exactly like ask_pipeworx. It clearly distinguishes itself from siblings by naming ask_pipeworx and positioning itself as the 'experimental edge' while most sibling tools are narrow-purpose (banking_regulation, polymarket_arbitrage).

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

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

Gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state ('No candidate is active right now... this currently matches ask_pipeworx exactly') so an agent can decide sensibly. It does not explicitly state when NOT to use it or how it differs from ask_pipeworx_grounded, but the routing intent 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?

Beyond the readOnly/idempotent annotations, the description reveals crucial behaviors: it only uses tool result content, it returns a structured response with evidence and confidence, and it explicitly refuses with defined refusal_reason values when data doesn't answer. The cost trade-off (one extra LLM call) is also disclosed. This is substantial behavioral disclosure that goes well beyond what annotations provide.

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

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

The description is dense but every sentence serves a purpose: purpose, routing mechanism, output contract, refusal reasons, usage guidance, and cost trade-off. It is front-loaded with the core differentiator ('hallucination-resistant') and the structure flows logically from behavior to return format to usage. No filler or repetition.

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

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

Given the tool's complexity, the description covers all aspects an agent needs: what it does, how it differs from ask_pipeworx, the exact success and refusal output shapes, when to use it, and when to avoid it. The return format is fully specified despite no output schema, and the refusal reasons enumerate edge cases. The description is complete for selecting and invoking 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?

The input schema has 100% coverage with all parameters being aliases for 'question' and full descriptions. The description adds no parameter-specific semantics beyond 'fills arguments' which is generic. Since the schema already documents every parameter thoroughly, the baseline 3 is appropriate.

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

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

The description clearly states this is a 'hallucination-resistant answer mode for high-stakes reads' and explains it routes like ask_pipeworx but extracts answers using only tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing groundedness, evidence, and refusal behavior. The verb 'asks' and resource 'Pipeworx' are implicit but made concrete through the detailed behavior description.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains. It also gives the alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is a clear when-to-use vs. when-not-to-use comparison with a named sibling.

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 and idempotent hints; the description adds behavioral context such as forgiving input handling, paragraph stripping, and behavior for parts vs sections, which is valuable beyond the annotations.

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

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

The description is well-structured with multiple lines and examples, front-loaded with the core purpose. Every sentence adds value, though it could be slightly more concise without losing content.

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

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

Given the single parameter, lack of output schema, and high input complexity, the description fully covers return values ('exact regulatory wording currently in force', section list for parts) and input variations, making it complete for its 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?

The input schema provides 100% coverage with a detailed description for 'citation'. The tool description expands on this with extensive examples and forgiveness rules, adding significant meaning beyond 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 explicitly states it retrieves the full text of a single banking regulation by citation or Regulation letter, with a specific verb ('Get') and resource ('banking regulation'). It distinguishes from the sibling 'banking_regulations_search' implicitly by focusing on a single regulation versus search.

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 and multiple examples of when to use the tool (e.g., 'what does Regulation E require', 'read 12 CFR 1026.19'), but does not explicitly exclude scenarios like searching across multiple regulations, which would be better served by the sibling tool.

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

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

Annotations already declare the tool read-only and idempotent. The description adds useful behavioral context such as 'Keyless' (no API key needed), and explains the search results format (citation, heading, excerpt, URL), which enhances transparency.

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

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

The description is fairly long but well-structured with examples and topics front-loaded. While not terse, it earns its length through valuable detail.

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

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

For a search tool with no output schema, the description fully explains the input parameters, return format, and usage context, leaving no significant gaps.

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

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

Schema coverage is 100% for both parameters, and the description provides extensive examples for the 'query' parameter and notes the 'limit' range (1-20, default 10), adding value beyond the schema.

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

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

The description clearly states it is a 'keyword search across the US banking regulations' and lists specific agencies and example queries, making the purpose unambiguous and distinct from siblings.

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

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

The description provides numerous example queries and topics, effectively guiding when to use the tool. However, it does not explicitly differentiate from the similar sibling 'banking_regulation' or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: low-confidence matching short-circuits, closed markets skip fan-out, wide spreads flagged, resolution-rule risk parsed, and news fallback behavior. This substantially enriches 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 front-loaded with the primary purpose and input types. While comprehensive, it includes extensive detail (e.g., full fan-out examples, response shape details) that could be trimmed or structured with sections for easier parsing. Still, every sentence adds value for agent decision-making.

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

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

Given the tool's complexity (multiple input forms, varied fan-outs, edge cases), the description covers all necessary context: resolver confidence, parent event extraction, closed markets, liquidity warnings, cancellation rules, and response size management via include_raw. It is complete without an output schema.

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

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

The input schema has 100% parameter description coverage, with clear descriptions for market, depth, and include_raw. The tool description adds no additional param-specific meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison), leaving no ambiguity about what the tool does.

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

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

The description explicitly recommends use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_arbitrage, missing an opportunity to guide agent 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?

Beyond annotations, the description details exact data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, return format with sorted results and citation URIs, and that it makes one parallel call.

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 concise example queries, each sentence adds value without repetition, and information is well-structured across three short paragraphs.

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 all necessary aspects: use cases, data sources, parameter meanings, result format, sorting, and efficiency advantage; no output schema needed given the clear description.

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?

Adds significant meaning beyond schema: explains that 'type=company' pulls specific financial metrics and 'type=drug' pulls adverse events, approval counts, and trials; gives concrete examples for values (tickers/CIKs for company, drug names) and min/max constraints.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, provides example queries like 'compare X and Y' and 'rank these companies', and specifies the data pulled for each type.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', and quantifies that it replaces 8-15 sequential lookups, giving strong implementation guidance.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses account/payment requirements, depth-specific hop and gap-recovery behavior, latency expectations, output fields, the never-invented guarantee, and citation fetchability. It adds substantial behavioral context and does not contradict 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 important routing facts: account required, alternative tool, scope, and best use. It loses a point because it is quite long, contains a duplicated sentence about using ask_pipeworx, and some transitions are run-on, but nearly every detail carries real 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?

With no output schema, the description carries the full burden of explaining return values and behavior. It covers the findings packet, gaps, contradictions, hop, citation_uri, excerpting behavior, latency, and depth semantics, giving an agent everything needed to call and interpret the tool confidently.

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, but the description adds useful meaning beyond the schema: concrete example questions, prose around depth behavior, the paid-plan implication of thorough, and the hop/citation semantics. This earns an upgrade from the baseline.

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

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

The description states a specific action and resource: grounded multi-source research across Pipeworx's structured data sources, using parallel routing to tools. It explicitly contrasts with open-web search and distinguishes itself from ask_pipeworx by targeting broad or multi-part structured-data 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?

It gives explicit when-to-use guidance with examples, and directly says to use ask_pipeworx instead for single lookups and for unsigned-in users. It also discloses account and plan prerequisites for depth=thorough, so an agent can route correctly.

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. The description adds valuable context: returns top-N relevant tools with names, descriptions, full input schemas (with curated examples), and each result is ready to call directly. It also notes that no second schema lookup is needed, which informs the agent about efficiency. 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 informative but somewhat verbose, listing many domains and details. It front-loads the core purpose, but the length could be trimmed without losing meaning. Every sentence earns its place, but overall conciseness is moderate.

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

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

Given the absence of an output schema, the description adequately explains what is returned (top-N relevant tools with names, descriptions, full input schemas). It addresses the purpose, usage, and behavior. Parameter count is high but schema covers all with descriptions. Annotations provide safety context. The description is complete enough for the agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100% (all 6 parameters have descriptions). The description repeats the main parameter purpose ('Natural language description of what you want to do') and lists aliases, but does not add significant meaning beyond the schema. The schema itself includes examples, which aids understanding. Baseline 3 is appropriate because the description does not compensate for any lack of schema detail.

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: 'Find tools by describing the data or task.' It uses specific verbs (find, browse, search, look up, discover) and explicitly lists domains (SEC filings, financials, etc.), distinguishing it from sibling tools that perform specific tasks. The description makes it evident this is a discovery tool, not a direct data retrieval tool.

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists scenarios for use ('when you need to browse, search, look up, or discover'). While it does not explicitly state when not to use, the guidance is clear and contextually 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?

With annotations already declaring read-only, idempotent, and non-destructive behavior, the description goes far beyond the default burden. It details the fan-out across eight sources, explains that sources_used/sources_failed report per-company status, notes that an empty FDA section is expected for small-molecule-only companies, discloses the USPTO API sunset soft-fail behavior, and specifies that private companies return resolved:false with an explicit notes line. This gives an agent accurate expectations for failure modes and edge cases.

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 every sentence carries operational value: trigger examples, scope, source list, return highlights, failure semantics, and input variants. It is front-loaded with user query examples and the central 'ALWAYS PREFER' routing guidance. It could be improved with bullets or section breaks for easier scanning, but for the complexity of the tool, the density is justified.

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

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

Given that there is no output schema, the description compensates thoroughly by summarizing return fields (cik, company_name, recent_filings with URIs, fundamentals, sources_used/sources_failed) and expected edge cases (private company, empty FDA section, source soft-fails). It even notes future support for person/place. An agent has enough information to call the tool correctly and interpret results across the full range of inputs.

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

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

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaningful context beyond the schema: examples of valid inputs ('AAPL', '0000320193', 'Modern'), the zero-padded CIK requirement, names resolving via SEC EDGAR, and the behavior for private companies. It also reinforces that `type` and `value` are interchangeable regardless of which enum is used. This is helpful but largely overlaps with the schema's existing parameter descriptions, so a 4 rather than a 5 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: 'full cross-source profile of a US public company in ONE parallel call.' It lists concrete trigger examples ('Tell me about X', 'brief me on Tesla', 'company profile for Microsoft') and distinguishes itself by instructing 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This clearly separates it from tools like resolve_entity or deep_research by scope and methodology.

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

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

The description explicitly says when to use this tool instead of alternatives: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers input selection rules (ticker, zero-padded CIK, or company name), resolution behavior, and what to expect for private companies. The condition 'when the user asks for a holistic view' is a concrete decision rule for an agent.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description reinforces this with 'delete' and adds context about clearing stale or sensitive data. No contradiction, and the description adds marginal 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 concise sentences. First sentence states purpose, second provides usage guidelines. No unnecessary words or repetition. Well-structured for quick comprehension.

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

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

For a simple tool with one parameter and no output schema, the description is sufficient. It covers purpose, usage context, and relation to siblings. No missing critical information.

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

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

The only parameter 'key' is described in the schema as 'Memory key to delete.' The description does not add extra meaning; schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' with a specific verb and resource. It distinguishes from siblings by mentioning 'pair with remember and recall.' This leaves no ambiguity about the tool's purpose.

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

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

Provides explicit scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall. However, it does not explicitly state when not to use it or list alternative tools for similar tasks.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the process: fetches page, extracts title/description/key links, and emits standard format. 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 a short, front-loaded paragraph with three sentences. Every sentence adds value: purpose, process, and use cases. No redundant information.

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

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

Given 2 parameters with full schema coverage and no output schema, the description adequately covers input purpose, process, and output format (single text blob at site-root/llms.txt). It is complete for an AI agent to select and invoke the 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% for the two parameters. The description adds context by explaining that max_links limits the number of link entries and gives default/max values, going beyond the schema's basic description.

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

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

The description clearly states the verb ('generate'), resource ('llms.txt file'), and purpose ('so AI crawlers can index the site cleanly'). It specifies the action and output, and distinguishes from siblings by focusing on a specific file generation task.

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 lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitors. It provides clear context on when to use but does not explicitly state 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?

Annotations already mark readOnlyHint=true, destructiveHint=false, etc. Description adds value by listing exact return fields and clarifying default behavior (active only). No contradictions.

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

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

Two compact sentences: first covers purpose and returns, second covers usage guidance. No wasted words, front-loaded with key info.

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

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

For a simple list tool with one optional param and no output schema, the description fully covers purpose, return fields, and usage context. Nothing 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% with a clear parameter description. The description adds no extra detail beyond what's in the schema, but the parameter is simple boolean. Baseline 3 is appropriate.

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

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

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

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel'. This tells when to use and implies when not to use (not for mutation). No explicit alternatives but siblings cover those cases.

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

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

Annotations are all false, so the description carries the full burden and excels. It discloses the claim_token workflow, daily digest reading, rate limit (5 per identifier per day), and that it's free with no quota 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 longer than typical, but front-loaded and well-structured, starting with the core action and then layering usage, exclusions, mechanics, and rate limits. Every sentence adds necessary context; a small deduction for length, but no 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?

With 4 params, nested objects, and no output schema, the description covers all key aspects: when to use, what to include, token retrieval, rate limits, and cross-server guidance. It fully compensates for the sparse annotations and missing output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token lifecycle (filing returns it, later passing it reads status/changes) and advising message content ("don't paste the end-user's prompt"), which goes beyond schema descriptions.

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

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

The description opens with a specific verb+resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It clearly distinguishes this from siblings by scoping it to Pipeworx tools only, even naming the exclusion of other MCP servers.

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

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

Explicitly states when to use: "Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)." It also gives a when-not-to-use with alternatives: "if the tool came from a different MCP server ... file it with that server instead."

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds that data is 'self-aggregating signal — derived from CF analytics-engine, no PII' and 'Cached 5min-1h depending on window'. This provides valuable 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?

The description is about 4 sentences, well-structured with purpose first, then use cases, then data derivation. The introductory phrase 'What other AI agents are calling on Pipeworx right now.' is slightly redundant but not harmful. Efficient overall.

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 has no output schema, so the description should explain the return format. It only mentions 'top tools, top packs, and total call volume' but not the structure (e.g., arrays, objects). Caching behavior is noted but not how to interpret time windows in results. More detail would help.

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 schema description already explains the enum options and their effect. The tool description repeats 'Shorter windows... longer windows...' which is already in the schema description, adding no new meaning.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'. The verb 'Returns' and specific resource list differentiate it from siblings like 'discover_tools' or '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?

Three explicit use cases are listed (discovering hot data sources, confirming popular tool, aligning use case). Window selection guidance is provided ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). No explicit when-not-to-use, but positive guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds extensive behavioral context: monotonicity checks, partition-sum verification, semantic anchor with Jaccard similarity, partition filter for placeholder slugs, fill check against live CLOB depth, and explanation of when not to trade (realizable_edge_pp <= 0). No contradictions with annotations.

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

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

The description is lengthy but dense with relevant information. It is front-loaded with the main purpose and then provides detailed explanations. While every sentence contributes value, some sections could be slightly shortened without loss of clarity. Still, it avoids redundancy and is well-organized.

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 the lack of an output schema, the description thoroughly explains the response structure (opportunities[], partition_check details, fill check results). It covers the algorithm, edge cases (placeholder filter, low similarity), and references a sibling tool for custom sizing. This provides a complete understanding for an AI agent to use and interpret results.

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

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

Schema coverage is 100% with both parameters documented. The description adds significant value by explaining the meaning of each parameter, providing examples, and detailing how each mode behaves. For example, it explains that 'event' walks child markets and checks date-axis/threshold-axis ordering, while 'topic' searches related events and runs comparator on the union.

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 that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying the unique mechanism and modes (trending scan, event, topic).

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

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

The description explicitly explains when to use each mode: no args for trending scan, event for specific market slug, topic for cross-event scanning. It provides examples and explains the rationale for choosing each mode, making it easy for an AI agent to select the appropriate 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: cache TTL, model formulas, diagnostic output, and the 'Market moved X.Xpp in 24h' warning. 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 comprehensive but overly verbose (approximately 500 words). It is structured with segments and bullet points, but could be more concise while retaining key details. Some information could be condensed.

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, 3 segments, no output schema), the description is remarkably complete. It explains the response structure, caching, edge cases (Fed bets, placeholders), and diagnostic output, leaving little ambiguity for the agent.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances understanding by providing context for each parameter, such as explaining that min_edge_pp is net of slippage and min_liquidity prevents walking the book. It adds value beyond the schema descriptions.

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

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

The description clearly states that the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses specific verbs and resources, and distinguishes from siblings by focusing on this unique angle and segmentation into three model families.

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 frames the tool for 'what should I bet on today' and explains the three opportunity segments. It provides guidance on when to use via the category_filter parameter and mentions tradeable-edge knobs. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds significant behavioral context: TTL limits (60 days), snapshot start conditions, and that decay is based on daily closes (not intraday). 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 well-structured with separate sections for args, response, and limits, but it is verbose (multiple sentences for response layout). Some redundancy exists (e.g., explaining window again). A more concise version would improve readability.

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

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

Given no output schema, the description thoroughly explains the three-part response (tracked, expired, snapshot_dates) with field details. It also covers limits (60-day TTL, snapshot enablement) and data provenance, making the tool fully understandable without external documentation.

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

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

Schema covers both parameters with descriptions. The description supplements by clarifying defaults (days=14, window='1wk'), bounds (days max 30 vs schema's clamp 2-30), and the meaning of 'window' as snapshot family. This adds practical usage context beyond the schema.

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

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

The description clearly identifies the tool as providing edge persistence and decay telemetry, with a specific verb ('answers') and resource ('daily polymarket_edges snapshots'). It distinguishes from the sibling 'polymarket_edges' by focusing on time-series behavior rather than raw edge data.

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

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

The description implies usage context (comparing fresh vs old edges) but does not explicitly state when to use this tool versus alternatives like polymarket_edges. No 'when not to use' or exclusion criteria are provided.

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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, the description adds significant behavioral context: it walks the order-book ladder, returns specific fields like slippage, max_fillable_usd, verdict, and warns about forced directional risk from partial basket fills. 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 relatively long but well-structured with uppercase section labels (REQUIRES, SINGLE-MARKET, BASKET) and front-loaded purpose. Every sentence adds value, though the density could be slightly reduced. No 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 complexity (two modes, no output schema), the description is remarkably complete. It explains all major return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk) and ties usage to sibling tools. No omissions.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by explaining the difference between single-market and basket modes, default values, and how size_usd is interpreted differently for buys vs sells. The additional context goes beyond the schema but is not revolutionary.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It uses specific verbs like 'check' and specifies the resource (Polymarket order books). This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why not to skip it (partial basket fills convert arb to directional). Provides clear context for when it's necessary versus alternatives.

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

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

The description is exemplary: it discloses that compatibility warnings can co-occur with matched pairs, that null temporal_alignment means 'could not be computed' rather than aligned, that spreads are gross of Kalshi fees, that pairs are unverified keyword matches, and that unknown-type legs are never paired. These behaviors go far beyond the readOnly/openWorld/idempotent annotations and fully prepare an agent for the tool's quirks.

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 (modes, response, safety fields, codes, flags, fees, counters, caveat) and front-loaded with the core definition. A few details are reiterated (e.g., temporal mismatch appears in both the code list and per-entry flags), which keeps it from a 5, but the length is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining the response, and it does: it enumerates the returned fields, explains each compatibility code and per-entry flag, defines the temporal_alignment object, describes fee handling, and clarifies which comparisons are skipped. It even warns about the current reliability of the pre-mapped shortcuts. Nothing essential for correct invocation or interpretation 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?

The schema covers all three parameters at 100%, including the enumerated topic values and override semantics. The description adds context about modes running the same matcher and auto-fetch behavior, but does not substantially expand parameter meaning beyond the schema. With high schema coverage, the 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 opens with a precise verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It is specific about the computed quantity (probability spread) and the two venues involved. It does not explicitly contrast with siblings like polymarket_arbitrage or polymarket_edges, so it stops short of full sibling differentiation.

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

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

The description thoroughly explains the two invocation modes (pre-mapped topic vs explicit tickers) and when each is appropriate, and it warns that most pre-mapped topics currently return compatibility_warning. However, it never names sibling tools or states when to choose this over polymarket_arbitrage or polymarket_edges, leaving alternative-routing implicit.

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

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

Annotations cover read-only and idempotent behavior. Description adds valuable context about scoping (anonymous IP, BYO key, account ID) and pairing with remember/forget.

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

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

Two concise sentences front-loading the core purpose. Every sentence adds value with no 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 single optional parameter and no output schema, description fully explains tool's functionality, dual modes, scoping, and integration with sibling tools.

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 description for 'key'. Description adds practical insight: omitting key lists all keys, and provides example key values (ticker, address, notes) 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 the tool retrieves a saved value or lists all keys, with specific verb-resource pairs. Distinguishes from siblings 'remember' and 'forget' by mentioning pairing.

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

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

Explicitly describes when to use: to look up stored context without re-deriving. Provides scenarios (ticker, address, notes). Does not explicitly exclude alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral detail about mark_read:true flagging events as read for subsequent calls, which is a state mutation but non-destructive, and confirms polling suitability.

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 four sentences, front-loaded with the core action, and each sentence adds necessary information without redundancy or fluff.

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

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

Considering no output schema, the description adequately hints at return fields (source, citation_uri, raw payload). It also mentions an alternative access method, making it self-contained for the tool's purpose.

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

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

Schema coverage is 100% with descriptions. The description adds value by providing examples like 'e.g. "sec_8k"' and clarifies the ISO timestamp for since, and explains the effect of mark_read beyond the schema's wording.

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 a subscription feed and returns most recent alerts with source, citation_uri, and raw payload. It distinguishes itself from sibling tools like list_subscriptions and subscribe by focusing on retrieving alert events from a persisted feed.

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

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

The description says 'Polls work fine' and mentions an alternative URL for scripts/dashboards, providing clear usage context. It does not explicitly compare to sibling tools but implies this is for polling the feed.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. Description adds value by detailing the fan-out behavior to SEC EDGAR, GDELT/GNews fallback, and USPTO, including soft-failures. No contradictions. Lacks mention of rate limits or error handling beyond the fallback.

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 a single paragraph packed with information, well-structured with example queries, source details, parameter usage, and sibling reference. Slightly long but every sentence adds value. Could be split for readability but 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?

Despite no output schema, description specifies return format: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' Parameters fully described. Annotations cover safety. Complete for a read-only tool with moderate complexity.

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

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

Schema description coverage is 100%, so baseline 3. Description adds meaning by explaining 'since' accepts ISO date or relative shorthand with examples, suggests typical '30d', and clarifies 'value' can be ticker or CIK. This goes beyond the schema.

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

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

Description clearly states 'change feed for a company in the last N days/weeks/months' and provides example queries. It distinguishes from sibling 'entity_profile' by recommending it for static profiles. The verb 'recent_changes' is specific and resource (company) is clear.

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

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

Description explicitly says 'Use entity_profile instead when you want the static profile', providing a clear alternative. It also gives example queries that imply usage contexts. However, it does not exhaustively list when not to use this tool versus all siblings.

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

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

Adds significant context beyond annotations: explains persistence per authentication status (authenticated users get persistent memory, anonymous sessions retain for 24 hours), scoping by identifier, and idempotent behavior. 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?

Single, well-structured paragraph front-loads the purpose, then covers usage and behavioral details. Every sentence adds value; no fluff or redundancy.

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

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

Given the tool's simplicity (2 required params, no output schema, no enums), the description fully explains behavior, scoping, and persistence. It also references companion tools (recall, forget) for completeness.

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 describes parameters well (100% coverage). Description adds value by providing usage examples ('subject_property', 'target_ticker') and explaining the purpose of the key-value pair, reinforcing 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?

Description starts with a specific verb and resource ('Save data the agent will need to reuse later'), clearly distinguishing the tool from siblings like recall and forget. It avoids tautology and provides concrete examples of use cases.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and recommends pairing with recall and forget. However, it does not explicitly mention when not to use or list alternative tools beyond the siblings.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds substantial behavioral detail beyond this: it returns a cross-source identity spine, labels identifiers by source, explicitly reports unresolved identifiers under `unresolved`, includes parent/ultimate-parent/children ownership when LEI resolves, and gracefully degrades if GLEIF or OpenFIGI is unavailable. This is rich, useful context with no contradiction to annotations.

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

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

The description is front-loaded and information-dense, but it is a single long paragraph with deeply nested parentheticals and semicolon-heavy clauses. It repeats some schema content (e.g., accepted entity types) and is harder to scan than it should be for an agent. Every piece is useful, but the structure undermines quick comprehension.

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

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

There is no output schema, so the description must explain return behavior. It names the returned fields per entity type (CIK, ticker, company_name, LEI with ownership, FIGI, RxCUI, ingredient, brand, citation), mentions unresolved-field behavior, and notes graceful degradation. This is largely complete for invocation, though an example output or explicit JSON shape would make it more concrete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by noting ISIN as an accepted company input (schema only lists ticker, CIK, or name), and by warning that bond issuers must be passed exactly as printed without trailing security-class words (e.g., "NEW YORK ST DORM AUTH" not "... revenue bonds"). This improves an agent's ability to supply the right value beyond the schema alone.

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

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

The description clearly states the tool's function: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." The opening examples of natural-language queries and the explicit "Use FIRST whenever you have a name but need an ID" establish a specific verb, resource, and role, distinguishing it from siblings like entity_profile or compare_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 gives a clear activation condition: "Use FIRST whenever you have a name but need an ID." It also lists supported input forms and entity types. However, it doesn't explicitly name alternative tools or say when NOT to use it (e.g., when an identifier is already known), so the guidance is clear but not fully exclusive.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining that probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized, along with output fields (score, confidence, signal density). No contradictions.

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

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

Two sentences plus a relevant quote. No fluff, front-loaded with the core action, and 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?

Despite lacking an output schema, the description clearly states the output format (ranked list with score, confidence, signal density). It also references the underlying tool ai_visibility_check. For the given complexity (4 params, no nested objects), this is sufficiently 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 covers 100% of parameters with descriptions, baseline 3. The description adds extra meaning for the 'entities' parameter by noting that the first entry is treated as the 'subject' for narrative and the rest as competitors, which is not in the schema.

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

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

The description uses the clear verb 'compare' with the resource 'AI visibility', explicitly mentions ranking and output structure, and distinguishes from sibling tool 'ai_visibility_check' which checks a single entity.

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 a specific use case: competitive AI-marketing audits, with an illustrative example quote. Does not explicitly state when not to use, but the context implies it's for multi-entity comparisons, with the sibling 'ai_visibility_check' available for single entities.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals partial failure behavior and potential delays: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' 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, followed by usage, return format, limitations, and behavior. Every sentence adds value; no redundancy. Efficiently uses space to convey complex functionality.

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

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

Despite no output schema, the description thoroughly explains what is returned (summary block with fields, per-advisory detail, links, recent alternatives). It also covers edge cases (partial failures, first-measurement delay). Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context by explaining the default behavior ('Defaults to the latest published version') and the purpose of the version parameter within the composite check. This goes beyond the schema alone.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, naming specific data sources (deps.dev, bundlephobia) and what they provide (license, advisories, version history, bundle size, etc.). It distinguishes itself from siblings by focusing on npm packages and being a one-call composite, unlike other search/validation tools.

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

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

Explicitly says when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear 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?

Discloses embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character offset in results, and input cap (200K chars with truncation flag). All beyond readOnly/idempotent annotations. 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?

Four sentences, each serving purpose: definition, use case, pairing with sibling, technical details. No redundancy. Front-loaded with core action.

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

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

Though no output schema, description explains return (top-N passages with offsets and similarity). Covers input limits, pairing, and technical constraints. Complete for a search tool.

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

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

100% schema coverage, description adds meaning: 'text' as document with max chars, 'query' as natural-language with examples, 'limit' with default and range. Extra context over schema but not essential.

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

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

Clear verb+resource: 'semantic search INSIDE a fetched record'. Examples (SEC 10-K, article) and contrast with ask_pipeworx_grounded distinguish from siblings. Specific about saving context and returning passages with offsets.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Details pairing with ask_pipeworx_grounded for grounding over passages. Provides clear context and 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?

Adds substantial context beyond annotations: account requirement, type-specific params, delivery constraints, webhook signing secret, auto-disable after failures. 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?

Description is detailed yet well-structured with clear sections for purpose, requirements, types, and delivery. All sentences are informative, no fluff.

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

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

Given complexity (3 params, nested objects, no output schema), the description covers prerequisites, all type options, delivery channels with constraints, and behavioral notes like auto-disable. Complete and actionable.

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

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

Schema coverage is 100%, but description adds rich examples and constraints for each parameter (e.g., enum values, nested shapes, phone verification, webhook signing). Adds value beyond schema.

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

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

Clearly states 'Create a proactive monitoring subscription' with return of new ID. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Explicitly requires Pipeworx OAuth account, lists all supported types with examples, and details delivery channels with verification, caps, and webhook behavior.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns example questions with exact tool+argument shape, and mentions full spread vs focused topic.

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?

Packed with information but slightly lengthy. Sentences are front-loaded with the main purpose, and every sentence adds value.

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

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

Given no output schema and one optional parameter, the description fully explains what the tool returns (categorized examples with tool calls) and when to use it.

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

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

Schema coverage is 100% (one optional param fully described). Description adds that omission gives full spread and lists example topic values, enhancing schema meaning.

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

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

Clearly states the tool is the onboarding entry point that returns category-bucketed example questions. Distinguishes from siblings like ask_pipeworx and discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to omit or pass the topic argument.

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 non-readonly, non-destructive, and idempotent. The description adds key behavioral context: ownership enforcement, deactivation instead of deletion, and preservation of historical events via 'recent_alerts'. No contradiction with annotations.

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

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

Three concise sentences with no wasted words. The action is stated first, followed by ownership and then behavioral details. Each sentence serves a distinct purpose.

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

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

Given the simple tool (one parameter, no output schema), the description covers all necessary aspects: what it does, ownership constraints, data mutation behavior, and relation to sibling tool 'recent_alerts'. No gaps.

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

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

Schema provides full coverage for the single 'id' parameter with its type and description. The description adds value by clarifying the id is 'returned by subscribe', linking it to the subscription source.

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

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

The description clearly states the action 'Cancel a subscription by id.' It specifies the resource (subscriptions) and the verb (cancel). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and the effect (deactivation).

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 ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior. It implies when to use (to cancel your own subscription) and mentions 'recent_alerts' for historical events. However, it does not explicitly state when not to use or list alternatives.

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

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

The description goes well beyond the annotations by explaining internal routing logic, the meaning of 'could_not_verify' (instructing it must not be used as evidence), the semantics of 'unsupported', and that it replaces multiple sequential calls. It also discloses that results include a citation and reasoning, which is useful behavioral context not present in annotations.

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

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

The description is long but every sentence earns its place: it opens with concrete example queries, defines the primary purpose, explains the two-path routing, lists return values, and clarifies critical interpretation nuances. The structure is logical and front-loaded with the core purpose, making it easy to scan.

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 covers the return types (verdicts, value, citation, reasoning) and provides necessary caveats for ambiguous outcomes. It explains the conditions for 'could_not_verify' and 'unsupported', and mentions that it consolidates multiple sequential calls, which gives the agent sufficient understanding of the tool's behavior and output.

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

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

The input schema already provides descriptions for both parameters (claim and tolerance_pct), so the baseline is high. The description adds valuable guidance on tolerance_pct, explaining how it overrides the implied tolerance and recommending values for hallucination detection, which goes beyond the schema description.

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

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

The description clearly defines the tool as a natural-language claim verification system with specific example queries and a list of possible verdicts. It distinguishes itself from generic Q&A tools by focusing on fact-checking and claim validation, and it differentiates the tool's behavior from siblings by mentioning the structured SEC EDGAR fast path for company-financial claims and the fallback to a grounded pipeline for other claims.

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

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

The description states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and provides routing details for different claim types. It does not explicitly name alternative tools or provide exclusionary guidance, but the use case is clear and the description implies a distinct role without overlapping with siblings like ask_pipeworx or deep_research.

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