Federal Register

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds context beyond annotations: default model (Workers AI Llama-3.3-70b, free), the need for an API key for Anthropic (with cost implication), and the return structure (per-model score, confidence, signals, raw_response plus combined view). No contradictions.

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

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

The description is front-loaded with the primary action and output, followed by default behavior, API key condition, return format, and use cases. It is efficient with no redundancy, though slightly lengthy at 4 sentences.

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 partially covers return values (per-model object with score, confidence, signals, raw_response, plus combined view) but does not detail what 'signals' or 'raw_response' contain, nor does it mention error handling or rate limits. More detail on output structure would improve 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 coverage is 100% with parameter descriptions. The description adds meaning beyond schema by specifying default model, explicitly listing supported models ('workers-ai' and 'anthropic'), explaining that _apiKey is passed directly to Anthropic API, and clarifying that context helps disambiguate entities.

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

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

The description uses a specific verb 'Probe' and clearly identifies the resource (LLMs for knowledge about entities). It explicitly states the output (score 0-100 per model) and distinguishes itself from siblings by specifying the functionality of scoring visibility per model, which is not present in similar tools like 'scan_competitor_ai_presence'.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to pass an API key for Anthropic probing. However, it does not explicitly mention when not to use this tool or contrast it with sibling tools like 'scan_competitor_ai_presence'.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context: the tool routes across 5,798 tools and 1517 verified sources, fills arguments automatically, and returns structured answers with citations. No contradiction with annotations exists, and the added routing/citation behavior helps an agent anticipate results beyond the safe-read profile.

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

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

The description contains strong front-loaded guidance, but it ends with the phrase 'START HERE for most questions' repeated several times without variation, which is pure redundancy. The long list of examples is useful, yet the repetition makes the description bloated and undercuts the conciseness that would otherwise earn a higher score.

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, this description is largely complete: it tells the agent when to use it, what inputs to pass, and what kind of output to expect (structured answer with citation URIs). There is no output schema, but the description covers the essential return characteristics. Minor gaps around failure behavior or cases where no tool matches are not critical for invoking it correctly.

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

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

Schema coverage is 100% because the single question parameter and its aliases are fully described. The description enriches the schema by clarifying that the question can be any natural-language factual request and expects the tool to resolve and fill downstream arguments. The detailed examples ('current US unemployment rate', 'adverse events for ozempic') give concrete grounding beyond the schema, exceeding 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 verb+resource: it routes questions to one of 5,798 tools and returns structured answers with stable pipeworx:// citation URIs. It explicitly names the domains it covers (SEC filings, FDA data, FRED/BLS, patents, etc.) and positions itself against web search, making its purpose unmistakable. This clear specificity distinguishes it from siblings even without naming them.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual current/historical data, lists trigger phrases like 'what is', 'look up', 'get the latest', and provides concrete examples. It names web search as the alternative and says 'START HERE for most questions', but it does not explicitly exclude sibling tools such as ask_pipeworx_grounded or deep_research, so it stops short of full when-not coverage.

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 valuable behavioral context beyond those: the experimental status, the possibility of candidate routing changes being live, the current no-candidate state, and that it is a full working router with no fallback. This gives an agent an accurate expectation of risk and behavior.

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

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

The description is slightly longer than necessary but every sentence earns its place: it defines what the tool is, explains the current experimental state, gives usage direction, and clarifies that this is not a stub. The key term 'beta' is front-loaded. Minor redundancy in the final clause does not significantly hurt clarity.

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

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

The description is complete for an agent to select and use the tool: it covers the routing scope, the current behavior, how to use it relative to ask_pipeworx, and the response shape. There is no output schema, but 'same response shape' as ask_pipeworx adequately addresses return expectations for a tool with a well-known sibling.

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

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

Schema description coverage is 100%, with the input schema fully documenting the 'question' parameter and its aliases. The description only says 'same arguments' as ask_pipeworx, which adds no semantic detail beyond the schema. Baseline 3 is appropriate since the schema already carries the parameter 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 this is the beta version of ask_pipeworx, a universal router with the same 5,798 tools, same arguments, and same response shape. It explicitly identifies what makes it distinct: candidate routing improvements tested live. This differentiates it from the stable ask_pipeworx sibling and other tools.

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

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

The description gives explicit context: use it exactly like ask_pipeworx when you want the newest routing, and results are compared against the stable router. It also notes that with no active candidate it currently matches ask_pipeworx exactly. It does not explicitly state when not to use it, but the beta framing and 'when you want the newest routing' make the intended usage 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?

Beyond the annotations, the description discloses the exact return shape, the refusal contract with specific refusal_reason values, and the strict constraint that only tool-result content is used. It also reveals the extra LLM call cost and the open-world refusal behavior, which annotations alone do not convey.

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

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

The description is dense but every sentence earns its place: purpose, behavior, return/refusal contract, usage guidance, and cost tradeoff. It is front-loaded with the key differentiator and structured so the agent can quickly determine fit.

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 and the absence of an output schema, the description is remarkably complete. It covers the success shape, failure/refusal shape, source grounding, cost, and when to prefer an alternative, so an agent has enough to invoke it correctly.

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

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

The input schema already provides 100% coverage for the single required question parameter, including aliases. The description adds no parameter-level detail, but it does not need to because the schema fully documents the parameter semantics.

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

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

The description states a specific verb and resource: it is a grounded, hallucination-resistant answer mode that extracts answers only from tool results and returns evidence. It clearly distinguishes itself from ask_pipeworx by emphasizing grounded extraction and refusal behavior, so an agent can differentiate it from siblings.

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

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

The description explicitly says when to use this tool: whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts. It also gives when-not-to-use guidance by stating it costs one extra LLM call vs ask_pipeworx and that ask_pipeworx should be preferred for casual lookups.

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

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

The description adds immense behavioral context beyond annotations: resolution confidence handling, closed markets, wide spreads, cancellation rules, news fallback, and response shapes. Annotations note readOnlyHint, openWorldHint, idempotentHint, destructiveHint, and the description aligns perfectly without contradiction.

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

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

The description is very long and detailed, covering many aspects. It is well-structured and front-loaded, but could be more concise. Some sections are verbose, making it less scannable for an AI agent.

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 covers response shapes, edge cases (low confidence, closed markets, wide spreads), cancellation rules, and safety mechanisms. It provides complete guidance for an AI agent to 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 descriptions; the description adds value by explaining depth defaults, include_raw usage, and market parameter formats. It also provides examples. Baseline 3 is elevated to 4 due to the extra explanatory context.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying inputs (slug, URL, or question text) and outputs (evidence packet + market-vs-model comparison). It is highly specific and distinguishes from sibling tools through its focus on Polymarket bets and comprehensive fan-out behavior.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides examples. It does not explicitly state when not to use, but the context is clear. Missing explicit exclusions prevent a higher score.

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

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

Annotations already mark it as read-only, idempotent, and open-world. The description adds valuable behavioral details: pulls latest data, handles off-calendar fiscal years, returns sorted results, and replaces 8-15 sequential lookups. No contradictions.

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

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

The description is detailed but well-structured with query examples upfront. It could be slightly more concise, but 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?

No output schema exists, so the description fully describes the return: paired data + citation URIs, sorted by primary metric. It covers data sources, fiscal year handling, and the tool's efficiency.

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 meaning beyond schema by explaining how values are used (tickers/CIKs for company, names for drug), constraints (2-5 items), and data sources (SEC EDGAR, FAERS).

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 comparisons of 2-5 companies or drugs in one parallel call, using specific data sources. It distinguishes itself from sibling tools like entity_profile and resolve_entity by explicitly preferring it over sequential lookups.

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

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

The description provides explicit usage cues with example queries ("which is bigger", "compare X and Y") and recommends ALWAYS PREFER over sequential lookups. It lacks explicit when-not-to-use guidance but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so no mutation risk exists; the description adds meaningful disclosure beyond that: decomposition/routing strategy, 5,798 tools in parallel, evidence packet shape, explicit gaps[] for unanswered facets, never-invented behavior, latency expectations (15-60s, up to ~90s for thorough), semantic excerpting rather than head-truncation, and resolvable citations only when fetchable. The account/paywall requirement is also disclosed. That is rich behavioral context without contradicting the annotations.

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

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

The description is dense and information-rich, but one long paragraph; the opening sentence is an aside about account requirements that delays the core purpose. The depth differentiation is explained twice (once early, once inside the multi-hop explanation), and the punctuation-heavy style with parentheticals and semicolons is harder to parse than bulleted sentences. It earns its content but not its formatting, so the trade-off is a '3'.

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

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

For a 2-parameter tool with no output schema, the description is unusually complete: it explains return format, citation resolvability, latency, gaps[], contradictions[], and session/paywall constraints. The only meaningful omission is an exact description of the output JSON structure (fields besides text, hop, citation_uri), which an output schema would normally supply, but absent that schema the textual description still resolves most ambiguity. Not a 5 because the packet's precise shape is left to discovery.

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 both parameters are already described in the input schema. The description nonetheless adds semantic nuance: broad/multi-part questions are fine because decomposition is the point, and it elaborates what quick/standard/thorough mean beyond the enum labels (single hop, gap-recovery, full iterative hop, contradictions scan). The depth parameter in the description adds a bit more operational meaning than the schema alone.

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

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

The description says this tool performs grounded multi-source research across 1,517 structured data sources in one call, decomposing questions into facets and routing to tools in parallel. It explicitly contrasts itself with open-web search and singles out ask_pipeworx as the alternative for signed-out users, so it is easy to tell apart from all 30+ siblings. It names return contents (verbatim evidence, confidence, source, fetched_at, citation, gaps[]) which further pins down 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 gives explicit when: broad/multi-part questions over structured data, with concrete examples ('compare X and Y's regulatory + financial exposure'). It tells when not to use it: if not signed in, use ask_pipeworx instead; for a single lookup use ask_pipeworx. It also explains which depth to choose, including that 'thorough' requires a paid plan — actionable guidance an agent can directly apply.

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, idempotentHint, destructiveHint. Description adds that results are 'ready to call directly, no second schema lookup needed.' No contradictions. Adds value beyond annotations.

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

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

Description is slightly long but well-structured, front-loaded with purpose, and each sentence adds value. Could be more concise but still effective.

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

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

Given the parameter count, sibling tools, and annotations, the description is fairly complete. It explains purpose, usage, and output readiness, though return format details are missing (no output schema).

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

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

Schema description coverage is 100%—all parameters have descriptions. The description reiterates natural language usage but does not add significant new meaning beyond the schema.

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

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

The description states 'Find tools by describing the data or task' and lists many example use cases. It clearly distinguishes itself from siblings as a discovery tool to be called first.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for when to use, though could mention 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 indicate read-only, non-destructive, idempotent behavior, and the description adds substantial context beyond that: USPTO PatentsView API sunset and soft-fail behavior, FDA section being empty for companies without biologics, source success/failure reporting, and name-resolution behavior via SEC EDGAR. These details help the agent interpret results correctly rather than misreading empty data as errors.

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

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

The description is long but front-loaded with illustrative user queries and a clear value proposition before diving into field-by-field behavior. It is dense and uses one long run-on structure, but nearly every clause contributes necessary information about failure modes and return expectations, so the length is mostly 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?

With no output schema, the description carries the full burden of explaining what the tool returns, and it does so comprehensively: CIK, company name, filings with pipeworx URIs, fundamentals, patents, contracts, FDA products, hiring data, news, LEI, plus sources_used and sources_failed. It also covers input resolution failure and expected empty sections, making it complete for safe invocation and result interpretation.

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 meaningfully augments both parameters: it states that type accepts 'company' or 'ticker' interchangeably, that value can be a ticker, zero-padded CIK, or company name, and that names resolve via SEC EDGAR's company-name match. It adds behavioral semantics beyond the schema's field descriptions without contradicting them.

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

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

The description opens with concrete query phrasings ('Tell me about X', 'brief me on Tesla') and defines the resource: a full cross-source profile of a US public company. It distinguishes itself from sibling lookups by emphasizing that it fans out across SEC, XBRL, patents, contracts, FDA, hiring, news, and GLEIF in one parallel call.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving clear selection criteria relative to more granular alternatives. It also covers expected edge cases like private companies returning resolved:false instead of failing, and empty sections being real 'no data' rather than bugs.

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

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

Description 'delete' aligns with destructiveHint=true. Adds context about clearing sensitive data. Does not exceed annotations significantly; annotations already cover destructive and idempotent hints.

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

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

Two sentences, first states purpose, second gives usage. No wasted words, front-loaded.

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

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

Simple tool with one param and no output schema. Description covers purpose, usage, and pairing. Complete for a delete 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 100% with description for 'key'. Tool description does not add further parameter semantics beyond schema. Baseline 3.

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

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

Clearly states verb 'delete' and resource 'memory by key'. Distinguishes from siblings 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: stale context, task done, clear sensitive data. Mentions pairing with remember and recall. Lacks explicit when-not-to-use but strong positive 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: it fetches the page, extracts title/description/links, and outputs standard markdown. No contradictions; the additional context is valuable.

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

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

The description is concise (three sentences), front-loads the primary action, and uses efficient prose. No redundant or trivial sentences.

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 low complexity (2 parameters, no output schema), the description adequately covers the process (fetching, extraction, output format) and use cases, leaving no critical gaps.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description does not add new semantic meaning beyond what's in the schema; it only reiterates the purpose. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It uses specific verbs ('generate', 'fetches', 'extracts') and distinguishes the output format and usage contexts, making it unambiguous.

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

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

The description provides three explicit use cases (indexing client sites, drafting for own projects, auditing competitors), offering clear guidance on when to use. It does not formally exclude cases or mention alternatives, but the context is sufficiently clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds specific return fields (title, abstract, etc.) and input format example. No contradictions; adds useful behavioral context beyond annotations.

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

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

Two sentences, no fluff. First sentence packs purpose and input format; second lists return fields. Front-loaded and efficient.

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

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

With output schema present and only one simple parameter, description is sufficient. Lists key return fields and input format. Adequate for the tool's low 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%, so baseline is 3. Description adds an explicit example (2024-12345) and clarifies it's a Federal Register document number, enhancing parameter understanding 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 it retrieves full details of a Federal Register document by document number. The verb 'get' and resource 'document' are highly specific. Distinguishes from sibling 'search_documents' which is for searching, not direct retrieval.

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

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

Implied usage: when you have a document number. No explicit when-not-to-use or alternative tools mentioned. Lacks comparison with 'search_documents' or other retrieval tools.

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

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

Annotation already declares readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and default active-only behavior, complementing annotations without contradiction.

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

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

Two sentences with no fluff. First states purpose and return fields, second gives usage guidance. Efficient and front-loaded.

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

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

Simple tool fully covered: annotations handle safety, description covers return fields, parameter, and usage guidance. No output schema needed; completeness is high.

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 parameter with description; description reinforces default behavior (active subscriptions) but does not add new meaning beyond schema. Baseline 3 applies.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource, explicitly listing return fields. Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit when-to-use context: 'review what you're monitoring before adding more or to find an id to cancel.' Implies alternatives but does not explicitly name sibling tools.

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

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

Annotations offer no safety hints (all false), so the description carries the burden. It discloses rate limiting (5 per identifier per day), accountless claim_token behavior, the daily review process, that it is free, and that it does not consume tool-call quota. It also warns against pasting end-user prompts, adding privacy-relevant context beyond the schema.

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 average, but every sentence earns its place: it front-loads the core purpose, then covers use cases, exclusions, token semantics, and operational constraints in a logical order. Nothing is redundant with the schema; the density is high without being rambling.

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 explains the important return behavior (claim_token and later status/resolution lookup), rate limits, and the workflow for follow-up. It is comprehensive enough for an agent to know when to call it, how to phrase feedback, and what to expect in reply.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter behavior beyond schema: claim_token usage is explained as returning a token for later lookup, and the 'no other arguments' constraint is made explicit. It does not deeply expand on context/message, but those are already well described 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the tool as a feedback channel and distinguishes it from the many research/query siblings by focusing on reporting issues, feature gaps, and praise for Pipeworx tools.

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

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

The description provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and an explicit exclusion: reports about tools from other MCP servers should be filed elsewhere. It even tells agents how to disambiguate uncertainty ('Pipeworx tool names are the ones this connection lists').

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds caching details (5min-1h), data source (CF analytics-engine), and privacy (no PII). This provides valuable operational context.

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

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

The description is three sentences plus a short list. It is front-loaded with the core functionality. Every sentence contributes meaningful information without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description adequately explains what is returned (top tools, packs, volume) and the caching behavior. No gaps are apparent.

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

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

The schema covers the parameter with enum and description. The description adds semantic guidance: shorter windows surface current hotness, longer windows show steady-state demand. This adds meaning beyond schema.

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

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

The description clearly states the tool returns trending tools, packs, and call volume from recent agent activity. This is a specific verb+resource that distinguishes it from sibling tools like ask_pipeworx or 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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, aligning use cases). The window parameter guidance is explained. However, it does not explicitly state when not to use this tool or name alternative tools.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds significant behavioral context: returns opportunities array, partition_check details, fill check with realizable edge, filtering of placeholder slugs, Jaccard similarity threshold. No contradictions. Warns when not to trade, enhancing transparency beyond annotations.

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

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

Description is thorough but slightly verbose. Includes repetitive details about partition_check and fill check across different parts. However, it is well-structured and front-loaded with the main purpose and modes, 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?

With no output schema, the description adequately explains the response structure: opportunities array, partition_check object, and fill check details. Also references sibling tool for custom sizing. Covers edge cases (placeholder slugs, similarity threshold, fill check limitations). Adequate for a complex tool with multiple modes.

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 value beyond parameter descriptions: explains event slug vs URL, topic as seed question, behavior differences, and edge cases like placeholder filtering. Provides examples that clarify parameter usage.

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

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

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes between modes (no args, event, topic) and provides specific examples. Differentiates from siblings like polymarket_fill_risk and polymarket_edges by describing unique functionality.

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 tells when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Recommends event mode and explains limitations of cross-event mode. Could mention when not to use this tool relative to siblings like polymarket_edges, but overall provides clear guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: caching (1h KV), edge calculation details (slippage, Kelly caps, model sources), filtering knobs, response structure with diagnostics, and Fed bet treatment. No contradiction with annotations.

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

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

The description is long but every sentence carries information. It is front-loaded with purpose and organized into segments. Could be slightly more concise in enumerating model details, but for a complex tool it is well-structured and informative.

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 9 parameters, no output schema, and complex logic (three segments, caching, diagnostics), the description is exceptionally complete. It explains the return structure, filtering behavior, edge calculation, and why certain data is excluded. Fully compensates for 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% with full descriptions. The description adds significant value beyond schema by explaining default behaviors, usage context (e.g., 'skips opportunities that are too small', 'Polymarket has zero trading fees'), and recommendations (e.g., 'bump for very thin partitions'). Enriches every parameter meaningfully.

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

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

The description clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with the specific goal 'what should I bet on today'. It distinguishes three model families and differentiates from other tools by focusing on discovery without paging hundreds of markets.

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 discovering betting opportunities and provides context about when to use ('what should I bet on today') and when not (Fed bets excluded from ranking due to unreliable signal without paid data). It does not name sibling alternatives but implies its role in the ecosystem.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context: history depth bounded by 60-day TTL, decay numbers from daily closes, and snapshot dates depend on cache-miss runs. 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 well-structured with sections for response format and limits. It is concise but not overly terse; every sentence adds value. Could be slightly more streamlined, but overall efficient.

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

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

No output schema is provided, so the description must fully explain return values. It does so with detailed explanations of tracked[], expired[], and snapshot_dates[], including field meanings and edge cases. Also covers limitations and data sources.

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% for both parameters. The description adds default values (14 days, '1wk' window) and constraints (max 30 days for days), which are not present in the schema. This enhances parameter understanding.

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

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

The description clearly states this tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. It distinguishes from siblings by focusing on historical snapshots and trends, separate from current 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 for historical edge analysis but does not explicitly state when to use this tool versus alternatives like polymarket_edges (current edges) or other sibling tools. No when-not-to-use or alternatives mentioned.

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

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

The description discloses behavior beyond annotations, such as walking the ladder, returning a verdict (clean|degraded|cannot_fill), and explaining that partial basket fills lead to unhedged directional positions. Annotations already indicate readOnlyHint, idempotentHint, so the description adds valuable context about output fields and risk flags.

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 moderately long but well-structured, starting with a clear one-sentence purpose, then separating single-market and basket modes with bold headers, and concluding with use-case guidance. Every sentence adds value, though it could be slightly more concise without losing meaning.

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

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

Despite no output schema, the description thoroughly documents return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict, thin_legs, forced_directional_risk). It also explains the dominant loss mode from partial fills, making the tool complete for its intended use.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema, e.g., explaining that size_usd for basket is 'settlement notional S (shares per leg; each share pays $1),' and clarifying side defaults in basket mode. 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 it is a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes two modes: single-market and basket/partition, and the verb 'check' with the resource 'order-book depth' is specific. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by being a pre-trade risk assessment.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the consequence of not using it (partial basket fills convert an arb into an unhedged directional position), providing clear context for when to choose this tool over 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses compatibility_warning/codes semantics, null temporal_alignment meaning, fee treatment as gross not net, skipped categories, and the rule that unknown metric_type/match_subtype legs are never paired. It even flags that pre-mapped topics often return warnings today.

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

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

The description is long and dense, but it is organized into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) with the core purpose front-loaded. Some redundancy and clause-heavy sentences prevent a 5, but little is filler.

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

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

With no output schema, the description carries full burden for explaining the response, and it delivers: leg-by-leg prices, top_spreads_pp flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. It also tells the agent to read compatibility fields even when matched_pairs is positive, closing a common misinterpretation.

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

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

Schema coverage is already 100%, and the description adds meaning: topic accepts ten named shortcuts that auto-fetch matching events, explicit ticker/slug override the topic-mapped side, and both modes run an identical token-overlap matcher. This is more than baseline, though some parameter details are already present 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?

Description opens by defining the tool as the cross-venue spread between Kalshi and Polymarket for the same resolving question, then spells out two modes that fetch/compare matching events. This clearly distinguishes it from siblings like polymarket_arbitrage and polymarket_edges by the specific venue pair and shared-question scope.

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

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

It explains exactly when to trust the result (equivalent bet shapes), warns that non-equivalent shapes are flagged, and tells the agent that pre-mapped topics are not automatically tradeable. It does not explicitly name sibling alternatives or exclusion criteria, but the mode selection and failure expectations are clearly stated.

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, so the safety profile is clear. The description adds value by explaining scoping to an identifier and pairing with remembering/forget. 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 two sentences, front-loaded with the main action, then provides examples and context. Every sentence is informative with no wasted words.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, good annotations), the description covers use cases, scope, and relationships with sibling tools completely.

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

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

Schema coverage is 100% for the single parameter, but the description adds meaning by explaining that omitting the key lists all saved keys, which goes beyond the schema's description.

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

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

The description uses a specific verb ('retrieve') and resource ('value saved via remember'), and distinguishes from siblings 'remember' and 'forget' by explaining it is the retrieval counterpart. It also clarifies the alternative behavior of listing all keys when no argument is provided.

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

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

The description explicitly states when to use the tool: 'look up context the agent stored earlier' and contrasts with alternatives like 'remember' (save) and 'forget' (delete). It mentions scoping but does not explicitly state when not to use it, which is a minor gap.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant value by detailing return fields (source, citation_uri, raw payload) and the side-effect of mark_read=true ('flag returned events read so the next call only shows newer ones'). No contradiction with annotations.

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

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

The description is a single paragraph of four sentences. Each sentence adds value, covering purpose, return format, filtering, mark_read, and polling. It is clear but could be more structured (e.g., bullet points) without losing information.

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

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

With no output schema, the description adequately describes return values and the mark_read mechanism. It also mentions an alternative access method. However, it does not specify the limit range (though schema does) or behavior when both mark_read and unread_only are set, leaving minor 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% so baseline is 3. The description adds extra meaning by providing an example for 'type' ('sec_8k'), specifying ISO timestamp for 'since', and explaining the behavior of 'mark_read'. However, it does not mention 'unread_only' beyond its schema description, so it does not fully compensate.

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 'Pull fired events from your subscription feed,' identifying the verb and resource. However, it does not explicitly differentiate from sibling tools like 'recent_changes' or 'recent_rules,' so it misses the top score for sibling distinction.

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 mentions that polling works and provides an alternative HTTP endpoint, but it does not give explicit guidance on when to use this tool versus other sibling tools. The context for filtering and mark_read is present but lacks when-not-to-use or clear alternatives.

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

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

The description adds significant behavioral context beyond the annotations: it fans out to multiple data sources, specifies the GDELT→GNews fallback logic, mentions USPTO's soft-fail due to API sunset, and describes the return format (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). Annotations already mark it as read-only and non-destructive, and the description reinforces this.

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 that front-loads the purpose with example queries, then details sources, then parameters. It is informative without being overly verbose, though it could be slightly more structured with bullet points. Every sentence adds value.

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

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

Given the tool has 3 required parameters, no output schema, and no nested objects, the description is fully complete. It explains the return structure (changes grouped by source, total_changes count, citation URIs) and covers behavior for each source. It also mentions limitations like USPTO soft-fail and that only 'company' is supported for type.

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

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

Schema coverage is 100%, but the description adds rich semantics: it explains 'since' accepts ISO dates or relative shorthand with examples ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for monitoring, and for 'value' clarifies ticker or CIK with examples. It also explicitly states that 'type' only supports 'company' currently.

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

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

The description starts with concrete example queries ('What's new with X', 'latest on Y') and clearly states it provides a change feed for a company from multiple sources (SEC EDGAR, GDELT/GNews, USPTO) over a time window. It distinguishes itself from the sibling 'entity_profile' by noting when to use that tool instead.

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

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

The description explicitly lists when to use this tool ('What's new with X' etc.) and provides an alternative: 'Use entity_profile instead when you want the static profile regardless of window.' It also gives guidance on the 'since' parameter, suggesting '30d' or '1m' for typical monitoring.

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 context: returns across all agencies (with examples), no topic filter, and lists return fields (title, abstract, etc.). No contradictions; description adds value beyond annotations.

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

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

Two sentences, front-loaded with main purpose, no redundant or extraneous text. Every sentence serves a purpose.

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

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

Given the tool's simplicity (1 parameter, no nested objects, output schema exists), the description fully covers behavior, return values, and usage context. 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 description coverage is 100% for the single parameter 'limit', which already includes default and max. Description does not add new information about the parameter beyond what schema provides. Baseline 3 is appropriate.

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

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

Description clearly states verb 'browse', resource 'most recently published final rules and regulations from the Federal Register', and explicitly states 'no topic filter'. It distinguishes from sibling tool search_documents for specific topics.

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 (browsing recent unfiltered rules) and when not to (specific topics), directing to search_documents as alternative. No ambiguity.

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

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

Beyond annotations (idempotentHint, destructiveHint), description adds key behavioral traits: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. 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?

Four sentences, front-loaded with main purpose, then usage, then details. No filler or repetition. 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 no output schema, the description fully covers what the tool does, how it stores data, and its lifecycle. Complete for a simple store operation.

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 value with examples for key (e.g., 'target_ticker') and explains value is any text. This enriches the schema meaning without redundancy.

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 saves data for later reuse, using specific verbs and resources (save, store, key-value). It distinguishes itself from sibling tools like recall and forget by mentioning pairing, making the purpose unambiguous.

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

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

Explicitly says 'Use when you discover something worth carrying forward', provides examples (ticker, address, preference), and pairs with recall/forget. This gives clear guidance on when to use and how it relates to alternatives.

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

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

Despite annotations declaring readOnly/openWorld/idempotent, the description independently discloses rich behavior: graceful degradation of LEI/FIGI enrichment, explicit `unresolved` identifiers, ambiguous matches returning `figi_candidates`, source-labelled identifiers, and internal cascading through multiple lookup endpoints. No contradiction with annotations exists.

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

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

The text is long but organized into a purpose statement, a routing directive, supported types, and behavior/degradation notes. It front-loads the core use and nearly every sentence carries operational value; only the heavy parenthetical asides keep it from being fully as clean as a 5.

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

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

With no output schema, the description carries the full burden of explaining returns. It does so thoroughly: identifiers returned per type, source labelling, explicit unresolved identifiers, `figi_candidates` on ambiguity, ISIN-to-legal-entity resolution, and graceful degradation when enrichment sources fail. An agent has what it needs to call and interpret the result correctly.

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

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

Schema coverage is 100% and both parameters are documented, but the description adds crucial semantic guidance: accepted input forms (ticker, CIK, ISIN, name), the entity-name-only rule with a concrete bond example, and a warning that trailing security-class words match nothing. This prevents a real invocation error the schema alone would not catch.

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

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

The description opens with concrete natural-language queries and explicitly defines the task: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the identifier domains (CIK, ticker, LEI, FIGI, RxCUI) and the two supported types, making it unmistakably distinct from sibling profile or comparison tools.

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

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

The line 'Use FIRST whenever you have a name but need an ID' is an explicit, actionable trigger that tells an agent when to invoke this tool, and the supported-type detail clarifies scope. It does not explicitly name sibling alternatives or state when not to use it, so it falls just short of a perfect routing instruction.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds significant context: it probes each entity with ai_visibility_check, ranks by score, and returns a structured list with specific fields. No contradictions.

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

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

Three sentences, each earning its place: purpose, mechanism, use case + output. Front-loaded and no filler.

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

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

With 4 params (all described in schema) and no output schema, the description covers output structure (ranked list with score, confidence, signal density) and explains the link to ai_visibility_check. Lacks explicit mention of models parameter behavior or API key caveats, but those are in the schema.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by clarifying the order of entities (first is 'subject' for narrative) and emphasizing the role of context. This goes beyond the schema's descriptions.

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

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

The description states a specific verb ('Compare'), resource ('AI visibility'), and scope ('across multiple entities side-by-side'). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (possibly generic) by detailing the competitive audit use case.

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 'Useful for competitive AI-marketing audits' and gives an example question. Implies when to use (comparative audits) and not (single entity check, which is handled by ai_visibility_check). However, it lacks explicit exclusion criteria or limits (e.g., entity count bounds).

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

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

Annotations indicate read-only, idempotent, non-destructive behavior, and the description adds critical runtime details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and failed sources are listed in 'sources_failed'. 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 informative without excessive verbosity. It is front-loaded with the core purpose and structured to cover details progressively. Minor tightening possible but overall efficient.

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

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

Given no output schema, the description enumerates all return fields (summary block, per-advisory detail, links, alternative versions) and explains limitations (NPM only, bundlephobia latency). It is complete enough for an agent to understand inputs, outputs, and edge cases.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted and that 'version' defaults to latest, which helps the agent form correct invocations.

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 specifies a composite check for npm packages across deps.dev and bundlephobia with a clear verb-resource pair. It distinguishes from sibling tools by detailing the exact scope and data sources, 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?

Explicitly states when to use the tool ('is X safe / popular / small?') and when not to (non-NPM ecosystems are directed to 'deps.dev:version directly'), providing clear decision support.

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. Description adds details about return format and the relevance ranker's tendency to surface old documents for sparse queries. No contradictions.

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

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

Description is somewhat long but well-structured: purpose first, then usage context, examples, and important note about 'since'. Every sentence adds value; 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 4 parameters with full schema coverage, an output schema, and a comprehensive description covering purpose, usage, parameters, and behavior, the description is complete and requires no additional 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?

Schema coverage is 100%, providing baseline 3. Description adds value by explaining the 'since' parameter's purpose and recommending its use, describing document types, and providing examples beyond schema.

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

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

The description clearly states the tool searches the US Federal Register by topic/keyword for specific document types, and explicitly contrasts with sibling tool 'recent_rules' which lacks topic filtering. It also lists return fields (title, abstract, agency, publication date, links).

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 use when question mentions a subject, contrasts with 'recent_rules' for unfiltered results, and provides examples and a warning about using 'since' to avoid stale results from the relevance ranker.

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 beyond annotations by detailing the embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), and character cap (200K chars with truncation). No contradiction with annotations.

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

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

The description is a single, well-organized paragraph that front-loads purpose and efficiently adds details without redundancy.

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

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

Given no output schema, the description explains the output (top-N passages with offsets and scores) and internal mechanics, making it complete for a complex 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?

Schemas cover 100% of parameters. The description adds value by providing query examples and reinforcing the character limit for text, slightly exceeding 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 it performs semantic search inside a fetched record, using a specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and the context of use.

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

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

It explicitly says to use when the record is too large for the prompt and pairs with ask_pipeworx_grounded. While it doesn't state when not to use, it provides clear context with examples.

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

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

Exceeds annotation hints by detailing behavioral aspects: requires OAuth, SMS daily cap, webhook auto-disable after failures, and delivery options. 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?

Well-structured with front-loaded core action. Slightly long due to comprehensive examples, but 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?

Covers all important aspects: return value, prerequisites, supported types, delivery channels, constraints, and error handling. Complete for a subscription tool without output schema.

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

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

Despite 100% schema coverage, the description adds significant meaning with real-world examples, type-specific parameter details, and delivery channel behaviors, far beyond what the schema provides.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID. It distinguishes itself from sibling tools like unsubscribe and list_subscriptions.

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

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

The description provides explicit prerequisites (OAuth account) and details on when to use each subscription type. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: returns example questions from live catalog, and mentions the tool shapes. No contradictions.

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

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

Description is detailed but front-loaded with purpose. Could be slightly more concise, but every sentence adds value for an onboarding tool.

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

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

Given no output schema, description reasonably explains return content. Parameter coverage is 100%. Sufficient for an onboarding tool without requiring deeper behavioral info.

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

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

Only one optional parameter 'topic' with enumerated values listed in description and schema. Description explains the meaning and effect of omitting it, adding significant value beyond schema.

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

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

The description clearly states the tool is the onboarding entry point for the agent, returning category-bucketed example questions with exact tool and argument shapes. It distinguishes from siblings by being about 'what can I ask' rather than executing queries.

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

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

Explicitly instructs to use this tool first when unsure of Pipeworx capabilities or to learn meta-tools. Provides context for optional topic parameter but lacks explicit when-not-to-use or alternatives.

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

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

The description adds value beyond annotations by explaining that the row is deactivated (not deleted) and historical events remain. This aligns with the annotations (destructiveHint=false) and provides critical behavioral context.

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

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

Two sentences with no redundancy. The action is front-loaded and every sentence adds necessary information.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description covers all essential aspects: purpose, ownership, and the deletion behavior.

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

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

The schema has 100% coverage for the single parameter, so baseline is 3. The description adds the context that the id is returned by subscribe, which helps the agent understand the parameter's origin.

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 cancels a subscription by id, using a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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, indicating you can only cancel your own subscriptions. This provides clear context, though it does not explicitly mention when not to use it or suggest alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description explains crucial behavior: the two possible processing paths, the exact verdict values, and the critical distinction between 'could_not_verify' (system failure) and 'unsupported' (no source found). This prevents misinterpretation of results, which is highly valuable.

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 carries essential information: trigger examples, use cases, path differentiation, return values, edge-case semantics, and efficiency benefits. It is well-structured and front-loaded with the most important purpose at the start.

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 exists, the description fully compensates by explaining return values (verdict types, actual value, citation, reasoning) and clarifying ambiguous cases. It also covers the tool's role in replacing multiple sequential calls, making it complete for a complex, high-stakes verification tool.

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

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

Although the schema already documents both parameters with examples, the description adds meaningful usage guidance, especially for tolerance_pct: it explains how it overrides implied tolerance, recommends values for hallucination detection (1–2), and states the default cap of 5. This goes beyond the schema's basic type/range 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 identifies the tool as a natural-language claim verification service, with specific trigger phrases and a clear verb-object structure ('verify the claim that…'). It distinguishes itself from sibling tools by detailing the structured SEC EDGAR/XBRL path and the grounded pipeline, showing it is the dedicated fact-checking 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?

Provides an explicit usage condition ('Use whenever the agent needs to check whether something a user said is factually correct') and differentiates between company-financial claims and other factual claims. It does not name specific alternative tools to avoid, but the context is clear enough for most cases.

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