nutrition

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

Annotations already mark read-only, idempotent, non-destructive. Description adds behavioral detail: default model is Workers AI Llama-3.3-70b (free), passing _apiKey enables Anthropic with cost implications, and return format per model. No contradiction.

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

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

Four sentences, front-loaded with core purpose and then model/cost, return format, and use cases. 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?

No output schema, but description explicitly documents return shape (per-model {score, confidence, signals, raw_response} + combined view). Combined with schema and annotations, the agent has enough to use the tool.

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

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

Input schema covers all parameters with descriptions (100% coverage). Description adds the default model name and cost behavior for Anthropic, which enhances the models/_apiKey semantics. Baseline 3, small increment.

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 names the resource (LLMs) plus the output (visibility score 0-100 per model). It distinguishes itself from siblings by emphasizing per-model scoring and return structure, not just asking questions.

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

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

States clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It doesn't explicitly exclude alternatives or name siblings, but the context is clear enough for an agent to decide when to invoke.

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. The description adds useful behavioral context: it routes questions, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. This supplements the annotations without contradicting them.

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

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

The description is front-loaded with the most critical 'PREFER OVER WEB SEARCH' instruction, but it is verbose. The enumerated domains and example list are helpful yet partly redundant with the schema examples, making the text longer than necessary for an 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?

For a broad routing tool with no output schema, the description covers purpose, scope, return format, citation behavior, default status, and escalation paths. It is sufficiently complete to select and invoke correctly without needing additional context.

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

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

Schema has 100% coverage with aliases and a clear 'question' description. The description reinforces this by showing the accepted natural-language style and giving many real-world example questions. It adds practical semantics beyond the schema's terse property description.

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

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

The description clearly states that ask_pipeworx routes factual questions to one of 5,529 tools across 1,455 sources and returns structured answers with citations. It explicitly contrasts itself with siblings like ask_pipeworx_grounded and deep_research, making its unique role as the default entry point unmistakable.

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

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

It provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), when-to-step-up (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), and concrete examples. This is exemplary usage guidance that leaves little 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?

The description goes well beyond the annotations by disclosing beta status, live candidate behavior, current no-candidate state, and fallback semantics ('this IS a full working router, just the experimental edge'). It complements rather than contradicts the readOnly/openWorld/idempotent hints, giving a full behavioral picture beyond the structured annotations.

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

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

The description is front-loaded with the 'Beta version of ask_pipeworx' identity and then efficiently covers current state, usage, and fallback. It is slightly verbose with repetition like 'identical universal router' and the parenthetical enumeration, but every sentence provides useful context without undue bloat.

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 experimental routing complexity, the description fully covers what an agent needs: what the router is, current candidate status, how to use it, and what fallback behavior to expect. The schema handles parameter details, and the mention of 'same response shape' combined with the sibling reference is sufficient despite no output schema.

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

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

The schema provides 100% coverage: question is described as natural language, and all five aliases (q, text, input, query, prompt) are explicitly documented. The description's mention of 'same arguments' adds no new meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, a universal router with the same 5,529 tools, same arguments, and same response shape. It distinguishes itself from the stable sibling by explicitly mentioning candidate routing improvements and the experimental edge, making its specific role unambiguous.

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

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

It gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains the evaluation context (results compared against the stable router) and notes the current state (no active candidate), allowing the agent to decide between this beta and the stable ask_pipeworx.

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

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

Annotations already cover read-only and non-destructive, but the description adds critical behavioral details: refusal reasons, evidence extraction, reliance solely on tool result, and the extra LLM call cost. It fully discloses the refusal contract and data truncation possibilities, going far beyond annotations.

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

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

The description is dense but front-loaded with the core purpose. It includes necessary details about output format and refusal reasons, which are essential for correct usage. While longer than typical descriptions, every sentence adds significant value.

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

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

The description provides a complete operating contract: success response shape, refusal reasons, cost implications, and use cases. It also contextualizes against ask_pipeworx, making it fully complete for an agent to decide and invoke correctly.

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

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

The input schema documents all six parameters as aliases for 'question' with descriptions, achieving 100% schema coverage. The description does not add parameter-level details, but the schema already fully conveys their meaning, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb ('extracts') and explicit scope. It distinguishes from sibling ask_pipeworx by noting same routing but grounded extraction using only the tool result.

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

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

It explicitly states when to use ('whenever an answer will be quoted, cited, or acted on...') and when not ('prefer ask_pipeworx for casual lookups'), including the cost trade-off. It also mentions the same routing as ask_pipeworx, providing clear alternative context.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond this by disclosing the resolver contract (match confidence, alternatives, suggestions), low-confidence short-circuit behavior, closed-market status, wide-spread illiquidity tradeability flag, news fallback attempts with retry_after_sec, and cancellation-rule parsing with EV impact. It also explains that both blocking routes lead to suppression of analysis fields. No contradiction with annotations.

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

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

The description is extremely long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose and usage. Each section provides valuable operational detail. However, the volume of examples and repeated edge-case explanations make it less concise than ideal; a more condensed version could retain all essential guidance while reducing reading load.

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 high complexity, no output schema, and rich annotations, the description is exceptionally complete. It covers input formats (slug, URL, question text), classifier taxonomy, concrete fan-out mapping for major categories, response field meanings (market, analysis, evidence), resolver contract with confidence levels, parent-event extraction, news fallback behavior, safety mechanisms for low-confidence and closed markets, and resolution-rule risk with concrete examples. An agent has enough context to use the tool correctly and interpret all relevant outcomes.

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 schema already documents market, depth, and include_raw with detailed descriptions. The description adds contextual examples (fan-out examples for market types, response shapes) that indirectly illustrate depth behavior, but does not introduce new parameter-level semantics beyond what the schema provides. Therefore a 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 a specific verb ('Research a Polymarket bet'), resource ('Polymarket bet'), and mechanism ('pulling the relevant Pipeworx data for it in one call'). It explains the full workflow (resolve, classify, fan out, return evidence packet + comparison) and differentiates from siblings via explicit use cases like 'should I bet on X' and 'is there edge in Z', which are not covered by general tools like ask_pipeworx or deep_research.

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

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

The description gives explicit usage scenarios ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'), which serves as clear guidance for when to select this tool over siblings. It also describes blocking behaviors for low-confidence or closed markets, but does not explicitly name alternative tools or state when NOT to use this tool, so it falls short of a 5.

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

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

Beyond the read-only annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, cash, adverse events), handling of off-calendar fiscal years, sorting behavior, and output format (paired data + citation URIs). This adds substantial context beyond annotations, explaining what the tool actually does.

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 information-dense and well-structured, front-loading trigger phrases and key instructions. Each sentence adds value—trigger examples, preference rule, data source details, sorting, and output—with no redundant fluff. Despite length, it is concise in purpose and every sentence earns its place.

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 (two entity types, comparative logic) and lack of output schema, the description still explains return format (paired data + citation URIs), sorting, and even edge cases like off-calendar fiscal years. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Although the schema provides 100% coverage, the description enriches both parameters with concrete examples (tickers/CIKs, drug names) and explains what data each type retrieves. This goes beyond the schema's basic field descriptions, offering meaningful additional 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 clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It uses specific trigger phrases like 'Compare X and Y' and 'X vs Y' to convey intent, and explicitly distinguishes itself from sequential single-pack lookups, making it distinct from sibling tools like entity_profile.

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

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

The description provides explicit guidance on when to use the tool via trigger phrases and directly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also clarifies behavior for company vs. drug types, offering a clear alternative recommendation without naming specific siblings, which is sufficient.

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

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

Annotations already establish safety (readOnly, openWorld, idempotent, non-destructive), but the description adds rich behavioral context: account/payment requirements, parallel routing across 5,529 tools, gap[]/contradictions[] output, guaranteed-fetchable citation_uri, semantic excerpting, performance expectations (15-90s), and a limitation (empty gaps for un-catalogued current news). No contradictions with annotations.

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

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

The description is long but front-loaded with the most critical information (account requirement and fallback). Every sentence carries operational value, though some information (e.g., contradictions[] mentioned twice) is slightly redundant. For a tool this complex, the length is justified.

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

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

With no output schema, the description fully documents the return value: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri guarantees. It also covers edge cases (current news, large records) and timing, making it complete for an agent to judge the tool's fit.

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

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

Schema covers 100% of parameters, but the description adds meaning beyond the schema by explaining how 'depth' behaves (standard re-angles gaps, thorough chases leads), noting the paid tier for 'thorough', and providing example questions. This goes beyond the schema's bare enum descriptions, though not dramatically.

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 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, and explicitly distinguishes it from open-web search and sibling ask_pipeworx. It uses specific verbs and resources, leaving no ambiguity about the tool's function.

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

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

The description offers explicit usage guidance: 'Best for broad/multi-part questions over structured data', and provides clear alternatives for different scenarios (single lookup → ask_pipeworx, breaking news → ask_pipeworx, no sign-in → ask_pipeworx). It also explains how depth levels affect behavior, giving an agent actionable selection criteria.

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

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

The description adds significant behavioral detail beyond the annotations, including the return format ('top-N most relevant tools with names, descriptions, and full input schemas'), the inclusion of curated examples, and the promise of 'no second schema lookup needed.' This provides context about output and efficiency that annotations do not cover.

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 contributes: purpose, domain list, return behavior, and usage context. It is front-loaded with the core purpose and structured logically, though the domain list could be trimmed for conciseness without losing essential information.

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

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

For a discovery tool with a simple schema and no output schema, the description fully explains what it returns, how to invoke it, and when to use it. It covers the `limit` parameter implicitly via 'top-N' and clarifies the query semantics with examples. 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples of query domains ('FDA drugs, FRED economic data, Census demographics') and clarifying that queries should describe a task or data need, which reinforces the semantics of the main `query` parameter beyond the schema's generic description.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Find tools by describing the data or task.' It also distinguishes itself from siblings by emphasizing discovery and the 'Call this FIRST' directive, positioning it as a meta-tool for enumerating 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 provides explicit when-to-use guidance ('Use when you need to browse, search, look up, or discover what tools exist') and a strong directive to 'Call this FIRST when you have many tools available.' It implies alternatives by noting 'not just one answer' but does not explicitly name alternative tools, so a 4 is appropriate.

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 read-only/idempotent annotations, the description discloses detailed behavior: fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; return field structure; patents API sunset with soft-fail; GDELT→GNews fallback; and acceptance of ticker/CIK only. This is valuable operational context the annotations do not provide.

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

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

The description is long but front-loaded with trigger examples, followed by a clear preference directive, then a compact semicolon-separated output breakdown. Every sentence adds value, though a few details repeat schema text, preventing a perfect 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?

Since there is no output schema, the description carries the full burden of explaining return values. It enumerates all return fields, explains fallback and soft-fail behavior, and notes input constraints. Given the tool's moderate complexity, this is complete and self-sufficient.

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

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

The input schema already covers both parameters with 100% description coverage, including the zero-padded CIK format and the names-not-supported note. The tool description repeats that guidance but adds no genuinely new parameter semantics beyond the schema. Baseline 3 is therefore appropriate.

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

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

The description opens with multiple user-intent examples and clearly states the tool's core function: 'full cross-source profile of a US public company in ONE parallel call.' It explicitly contrasts with sibling tools like resolve_entity and narrows scope to US public companies, making the purpose unmistakable.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names resolve_entity as the required precursor when only a name is given, and implies not for deep research by emphasizing a single parallel call.

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 destructiveHint and idempotentHint, and the description's 'Delete' is consistent with those. The description adds value by explaining the purpose of deletion (clearing stale/sensitive data) and how it integrates with remember/recall. It doesn't contradict annotations and avoids repeating safety 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 two sentences, with the core action in the first sentence and usage guidance in the second. Every word earns its place—no fluff or repetition of schema details. It is appropriately sized for a simple tool with one parameter.

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 parameter, full schema coverage, and clear annotations (destructive, idempotent), the description covers all necessary context: what it deletes, when to use it, and how it relates to siblings. An output schema is not needed for this simple deletion 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?

The input schema fully describes the only parameter 'key' as 'Memory key to delete.' Schema coverage is 100%, so the description's mention of 'by key' adds no extra semantic detail. Since the schema handles parameter meaning, a baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember (store) and recall (retrieve) by focusing on deletion. The purpose is unambiguous and directly tied to the tool's name.

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

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

The description explicitly says 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This gives clear, actionable guidance for when to invoke the tool. It also mentions pairing with remember and recall, providing workflow context relative to siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by explaining the internal process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond the annotations to describe the tool's behavior and output format.

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 and front-loaded: three sentences cover the action, process, output, and use cases. There is no redundancy or filler, and every sentence contributes meaningful information.

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

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

Despite having no output schema, the description explicitly states the output ('single text blob ready to drop at site-root/llms.txt'). It covers the tool's function, process, and practical application, making it fully complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% with both parameters (url and max_links) fully described, including default and max values. The description adds no additional parameter-specific details, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL' with specific resource (llms.txt) and purpose (AI crawler indexing). It distinguishes from siblings by focusing exclusively on llms.txt generation, which no other sibling 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 provides a clear 'Useful for:' section listing three concrete scenarios (client sites, own projects, competitor auditing). It gives clear context for when to use the tool, though it does not explicitly name alternatives or exclusions. This meets the 'clear context, no exclusions' bar.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint: false, covering the safety profile. The description adds transparent detail about the return fields and clarifies that only the caller's active subscriptions are listed. It does not add any further behavioral caveats, but for a simple read-only operation, this is sufficient.

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 concise sentences, each serving a distinct purpose: defining the action, listing the return fields, and giving usage guidance. There is no wasted wording or repetition, making it well-structured and easy to parse.

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

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

Given the tool's simplicity (one optional boolean parameter, no output schema), the description is complete. It states the scope, enumerates return values, and provides situational usage context. This gives an agent everything needed to correctly invoke and interpret the tool.

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

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

Schema description coverage is 100% for the sole optional boolean parameter include_inactive, which is already clearly described in the schema. The description adds no parameter-specific details, but since the schema fully covers it, a baseline score of 3 is appropriate.

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

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

The description opens with 'List the caller's active subscriptions,' which is a specific verb (List) + resource (subscriptions) + scope (caller's active). It also enumerates the returned fields (id, type, params, created_at, last_fired_at, fire_count), making it clear exactly what the tool returns. The usage guidance references monitoring and cancellation, implicitly distinguishing it 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?

The description explicitly provides two usage scenarios: 'review what you're monitoring before adding more' and 'to find an id to cancel.' This tells an agent when to use the tool relative to subscription management. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations are all false and provide no safety profile, so the description bears full burden. It compensates richly by disclosing a 5/day rate limit, free usage, the claim_token return for anonymous filings, daily digest review, and roadmap signal. No contradiction with annotations is present.

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 carries distinct value: purpose, use cases, exclusions, token flow, operational notes. It is front-loaded with the core purpose. Minor redundancy (e.g., repeated 'Pipeworx team') prevents a 5, but it remains economical for its complexity.

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

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

Even without an output schema, the description tells the agent what to expect (claim_token for anonymous filings, later status checks), covers rate limits and quota, and clearly defines scope boundaries. It is fully self-contained for correct selection and invocation.

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 a meaningful lifecycle beyond schema: 'Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed.' This elaborates on the claim_token parameter's usage and return semantics, earning 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 opens with a specific verb+resource+outcome: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback types (bug, feature, data_gap, praise) and explicitly distinguishes itself from other MCP servers' tools, setting it apart from sibling research/query 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?

Explicit 'Use when' clauses list bug, feature/data_gap, and praise triggers, plus an exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It also explains the claim_token usage flow and rate limit, leaving no ambiguity about when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data provenance, privacy, and caching behavior, which is useful despite the strong annotation coverage.

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

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

The description is about 100 words, front-loaded with the core function, then structured into bullet-like 'Useful for' items. Every sentence adds value: purpose, use cases, data origin, and caching. No fluff.

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

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

Despite no output schema, the description explicitly names deliverables (top tools, top packs, total call volume, (pack, tool, count)). It covers purpose, usage, behavior, and caching. Low complexity with one optional parameter, so this is complete.

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

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

Schema coverage is 100% for the sole parameter 'window', with enum values and a description already explaining the trade-off ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The description adds little beyond restating the window options, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It uses a specific verb ('returns') and resource (trending call data), and distinguishes itself from siblings like discover_tools by emphasizing it reflects 'what other AI agents are calling on Pipeworx right now.'

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

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

The description explicitly lists three 'Useful for' scenarios, providing clear guidance on when to use the tool. It does not explicitly name alternatives or state 'when not to use,' but the usage context is well-defined.

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 provides deep behavioral detail beyond the annotations: it explains the partition filter (placeholder slugs, >20% threshold), the semantic anchor (0.30 Jaccard similarity), the fill check (theoretical vs realizable edge at 1000 shares/leg), and the interpretation of realizable_edge_pp <= 0. It also discloses the output structure. This significantly exceeds what readOnlyHint and idempotentHint 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?

Although long, the description is tightly organized and every sentence provides critical operational detail. It is front-loaded with a one-sentence purpose, then neatly partitions into modes, filters, response format, and fill-check instructions. No filler or redundancy; high information density is appropriate given the tool's complexity.

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

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

The tool has no output schema, so the description shoulders the burden of explaining return values. It does so explicitly: 'Response: opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), and in event mode partition_check{...}'. It also covers edge cases like low similarity, placeholder filtering, and fill-check caveats. The description is self-sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description substantially enriches both parameters. For 'event' it gives real slug examples and explains it 'walks child markets, checks date-axis / threshold-axis ordering AND computes partition_check.' For 'topic' it gives seed question examples and describes the cross-event flattening and comparison behavior. It also introduces related concepts (Jaccard similarity, partition filter) 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?

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It provides a specific verb (find), a resource (Polymarket arbitrage opportunities), and a distinguishing method. It also outlines distinct modes (trending_scan, event, topic), which differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Usage guidance is explicit: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It explains when to use event mode vs topic mode and notes that cross-event mode catches patterns single-event misses. It also directs users to a sibling tool: 'For custom sizing use polymarket_fill_risk.'

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. The description goes far beyond this by disclosing caching behavior (1h at KV level), response structure, diagnostics, the 24h-move warning, and design quirks like partition arbs returning kelly_fraction_half=0 at the parent level. 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 well-structured and front-loaded with the core purpose. It uses labeled sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and parentheticals to pack information. Every sentence adds value, but it is denser and more verbose than a minimal description, so it loses one point for length.

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

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

With no output schema, the description fully details the response structure: by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips. It also explains caching, edge fields (edge_pp_net, kelly_fraction), and the Fed data caveat. This is complete for a complex tool with 9 parameters and 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 coverage is 100%, so baseline is 3, but the description adds substantial meaning. It explains how min_kelly interacts with partition arbs (doesn't filter them, use min_partition_leg_kelly instead), clarifies slippage context (zero trading fees but 20-50bp typical from spread/depth), and describes how max_spread_pp and min_liquidity gate tradeability. This goes well 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 opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly positions the tool for 'what should I bet on today' and details the three model families, distinguishing it from siblings that focus on arbitrage or fill risk.

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

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

The description gives explicit context for when the tool is useful: agents discover opportunities without paging hundreds of markets. It also explains how to use knobs like min_liquidity and max_spread_pp to filter for tradeable edges. However, it does not explicitly name sibling tools as alternatives when they should be used instead.

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

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

Annotations already include readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: 'history depth is bounded by the 60-day snapshot TTL and starts from when snapshotting was enabled; decay numbers come from daily closes of edge_pp_net (net of default slippage), not intraday'. It also explains data gaps ('gaps mean nobody scanned that day') and that expired opportunities are 'closed, resolved, or arbed away'. 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 is dense with useful information: purpose, arguments, response details, and limitations. It is well-structured with clear sections (Args, RESPONSE, LIMITS) and front-loaded with the core purpose. No fluff or redundancy.

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

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

Given the tool's complexity (two params, no output schema), the description compensates fully by explaining the response fields (tracked, expired, snapshot_dates) and the meaning of each, plus limitations. It covers data source, TTL bounds, and computation details, making it complete for an agent to understand behavior without an output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters with descriptions. The description adds minor context (e.g., 'lookback, default 14, max 30' and 'snapshot family'), but these largely mirror the schema. Since the schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers "how long has this edge existed and is it shrinking?"'. This specific verb+resource framing distinguishes it from sibling tools like polymarket_edges, which likely generates edges, while this tracks them over time.

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 strong contextual guidance: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)'. This implies when to use the tool (when edge age matters). However, it does not explicitly name alternatives or state 'when not to use', so it falls slightly short of a 5.

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

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

Beyond the annotations (read-only, non-destructive), the description reveals detailed behavior: it 'walks the ladder', returns a verdict (clean/degraded/cannot_fill), computes capture_ratio, identifies thin_legs and forced_directional_risk, and explains the basket fill mechanics. It also warns about partial fills converting arb into unhedged positions. This is rich behavioral disclosure that annotations alone do not provide.

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

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

The description is long, but every sentence carries unique information and it is well-structured: purpose, required-mode disambiguation, single-market breakdown, basket breakdown, and usage guidance. It is appropriately dense for the tool's complexity, though slightly verbose in places. No filler or repetition.

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

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

With no output schema, the description must explain return values—and it does: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers both operational modes and the risk context, making it fully self-contained for an agent.

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

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

Although schema coverage is 100%, the description adds significant semantic value: it explains that `market` and `event` are mutually exclusive modes, defines the default side logic for baskets, and clarifies that `size_usd` means 'max spend' in single-market and 'settlement notional' in basket mode. This goes far beyond the schema's parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and names the exact output concepts. This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains the rationale (thin books, partial fills create directional risk) and names the alternatives. This is textbook usage guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description thoroughly discloses behavior: response fields (leg-by-leg prices, spread[].top_spreads_pp), safety fields (compatibility_warning triggers, temporal_alignment, skipped_cross_type counters), and how mismatched bet shapes invalidate spreads. This significantly adds context needed to interpret results correctly.

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

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

The description is lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds critical information about result interpretation and edge cases, though some redundancy exists (e.g., explaining compatibility_warning in two places). It earns its length without being bloated.

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 must explain the response structure, and it does so comprehensively: raw probabilities, matched spreads, compatibility warnings, temporal alignment, and skipped-category counters. For a tool of this complexity, the description covers all necessary context for correct invocation and 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?

The schema already covers all three parameters (100% coverage), but the description adds semantic value by explaining the two modes and override behavior ('explicit kalshi_event_ticker + polymarket_event_slug for custom pairings' and 'Overrides the topic-mapped side'). This clarifies the relationship between parameters, enriching beyond bare definitions.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the resource and action. It distinguishes from sibling tools like polymarket_arbitrage by emphasizing cross-venue comparison and specifying two modes (topic shortcuts vs explicit tickers).

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

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

The description provides explicit guidance on when to use each mode ('topic' vs explicit tickers) and warns that 'pre-mapped ≠ tradeable' and 'most pre-mapped topics return compatibility_warning today.' It does not name alternative tools but gives clear when-not-to-trust instructions, which is strong usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral context beyond this, such as scoping to 'your identifier (anonymous IP, BYO key hash, or account ID)' and the ability to list all keys by omitting the argument. However, it does not disclose the return format or potential edge cases, so a small gap remains.

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

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

The description is three sentences long, each serving a clear purpose: function, use case, and scoping/pairing. It is front-loaded with the core action and contains no fluff or repetition.

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

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

For a simple tool with one optional parameter, no output schema, and no nested objects, the description covers the main usage context: retrieval, listing, scoping, and relationship to siblings. It lacks an explicit description of the return value (e.g., types), but this is not essential given the tool's simplicity and the agent's ability to infer the return from invoking it.

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

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

Schema description coverage is 100% (key is documented as optional, omit to list all keys). The description restates this but adds semantic richness by giving examples of what keys might store (target ticker, address, research notes), which helps the agent understand parameter purpose beyond the schema alone.

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

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

The description clearly states 'Retrieve a value previously saved via remember, or list all saved keys', using a specific verb and resource. It distinguishes from siblings by explicitly naming remember and forget, and provides concrete examples of use cases.

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

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

The description says 'Use to look up context the agent stored earlier' and explains the intended scenarios. It also directly references sibling tools: 'Pair with remember to save, forget to delete', giving explicit when-to-use vs alternatives 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?

The description discloses important behavioral traits beyond the annotations: mark_read:true flags returned events as read (a side effect), each event carries source/citation_uri/raw payload, and polling works fine. The annotations already cover readOnly/idempotent hints, so the description adds valuable context without redundancy.

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

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

The description is four sentences, each earning its place: action, return format, filtering and mark_read, and the alternative HTTP endpoint. It is front-loaded with the core purpose and avoids redundant 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?

Despite having no output schema, the description fully explains the return fields (source, citation_uri, raw payload), filtering options, side effects of mark_read, and polling behavior. The parameter schema handles the technical details, making this description complete for effective tool invocation.

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 description adds example usage for type (e.g., 'sec_8k') and clarifies the consequence of setting mark_read:true, which goes beyond the schema's field descriptions. Since schema coverage is 100%, the baseline is 3, but the additional context justifies a higher score.

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 pulls fired events from the user's subscription feed and returns recent alerts with source, citation_uri, and raw payload. The verb 'pull' and specific resource 'subscription feed' make the purpose unambiguous and distinct from sibling tools like list_subscriptions or recent_changes.

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 practical usage context: it mentions polling, filtering by type and since, and points to an HTTP alternative for scripts/dashboards. While it does not explicitly name a sibling tool alternative or state when not to use it, the guidance is clear and the alternative is provided.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds valuable context beyond annotations: multi-source fan-out, rate-limit fallback behavior, USPTO soft-fail due to API sunset, and structured output shape with citation URIs. No contradiction with annotations.

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

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

Although the description is long, it is front-loaded with user-facing query examples followed by a crisp definition. Every sentence adds useful information: sources, fallback logic, date formats, output shape, and alternative tool. Dense but well-structured for a multi-source 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?

The tool is complex (three upstream APIs, fallback, failure conditions, date parsing) and has no output schema. The description covers return values (changes[] group by source, total_changes, citation URIs), explains the soft-fail behavior, and notes the parallel-call efficiency. This is sufficient for an agent to invoke correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds a usage recommendation ('Use 30d or 1m for typical monitoring') but does not introduce new semantic meaning beyond what the schema already documents for type, value, and since.

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 strong action phrases ('What's new with X', 'change feed for a company') and clearly specifies the resource (SEC EDGAR, GDELT/GNews, USPTO). It explicitly distinguishes itself from sibling tool entity_profile by noting when to use the profile instead.

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

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

Provides explicit natural language query examples as triggers, explains the fallback chain (GDELT→GNews), and directly names the alternative tool (entity_profile) with a clear when-to-use condition. This enables an agent to select between recent_changes and entity_profile confidently.

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

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

Adds important behavioral details beyond annotations: key-value pairs scoped by identifier, persistence differences for authenticated vs anonymous sessions. This enriches the idempotentHint and non-destructive hints already present.

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 deliver purpose, usage, storage format, and persistence details with zero fluff. Information is front-loaded and every sentence earns its place.

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 two-parameter key-value store with no output schema, the description fully covers purpose, usage scenarios, storage semantics, and auth-dependent persistence. No critical information is missing.

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

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

While the schema already documents both parameters (100% coverage), the description reinforces with illustrative key examples and clarifies value accepts any text, adding useful semantic 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 saves data for later reuse across conversations or sessions, with concrete examples (resolved ticker, target address, user preference). It distinguishes from siblings by explicitly pairing with recall and forget.

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

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

Provides explicit when-to-use guidance ('Use when you discover something worth carrying forward') and names complementary tools (recall, forget), giving clear context for selecting this tool.

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

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

The description goes well beyond annotations by detailing that identifiers are source-labelled, unresolved identifiers are explicitly listed under `unresolved` rather than omitted, and LEI/FIGI enrichment degrades gracefully when external services fail. These are critical behavioral traits not captured by the read-only/idempotent annotations.

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

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

The description is lengthy but organized: example queries first, then a clear 'Use FIRST' directive, followed by structured type details. Every sentence contributes meaningful information, though some example queries could be condensed. The structure aids scanning.

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 of this complexity, the description is exceptionally complete: it covers purpose, accepted inputs, output identifiers per source, unresolved handling, fallback behavior, and the fact that it cascades through multiple endpoints. An agent can predict the return structure and edge cases without an output schema.

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

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

Schema coverage is 100% and already documents both parameters. The description enhances this by explaining what each type returns (e.g., company resolves CIK, LEI, FIGI with owner relationships; drug returns RxCUI, ingredient, brand) and clarifies accepted input variants, adding value beyond the schema.

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

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

The description opens with explicit example queries and states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from sibling tools like entity_profile or compare_entities by focusing on identifier resolution and specifies supported entity types.

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

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

It provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups, reinforcing when to choose it. However, it doesn't explicitly name alternative tools for other scenarios, which prevents a perfect 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 declare readOnly and idempotent hints, and the description adds process details: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score, confidence, and signal density. This goes beyond the annotation safety profile and enriches behavioral understanding.

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 compact and front-loaded: it states purpose first, then process, use case, and output. The example and return-field enumeration are purposeful, with no redundant information. Slightly longer than strictly necessary but 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 no output schema, the description compensates by listing the returned fields (score, confidence, signal density). It also explains the underlying probe mechanism and use case. Combined with annotations and schema, this provides a solid contextual picture without major gaps.

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

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

Schema description coverage is 100%, so the schema already explains all parameters fully. The description's mention of 'your brand + N competitors' aligns with the entities parameter but adds no new syntax or format details beyond the schema, staying at 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 opens with a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' This clearly differentiates it from the single-entity sibling ai_visibility_check and the generic compare_entities, while also stating its ranking and scoring output.

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

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

Provides a clear use case ('competitive AI-marketing audits') and an illustrative example ('does Claude know about us as well as our competitors?'), which implies when to use it. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses partial failure degradation, the 5-30s first-measurement delay, and the sources_failed field. This non-obvious composite behavior is valuable context the annotations 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, use cases, return fields, ecosystem limits, and failure behavior. It is front-loaded and well-organized, with no fluff.

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

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

Given no output schema, the description fully enumerates the return summary fields, per-advisory detail, links, and recent versions. It also covers ecosystem scope and failure modes, making the tool self-contained for an agent.

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

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

Schema coverage is 100% and describes package as npm package name with scoped support and version as defaulting to latest. The description adds no new parameter-level details beyond what the schema already defines, so the baseline of 3 applies.

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

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

The description opens with a concrete composite action ('should I add this npm package to my project' check in ONE call) and names the specific resources (deps.dev and bundlephobia). It clearly distinguishes from siblings like scan_competitor_ai_presence by focusing on npm package safety/cost, not competitive AI scanning.

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

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

Explicit 'Use whenever an agent asks...' with concrete example questions ('is X safe / popular / small', 'what does adding lodash cost me'). It also states the exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving an alternative path.

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

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

Annotations only declare readOnly/openWorld/idempotent/non-destructive; the description adds concrete implementation details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation/flagging, and output format (offsets, similarity scores). This far exceeds the bare 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 dense sentences deliver purpose, use-case, output format, implementation, and constraints without redundancy. The critical "when to use" and pairing are near the front.

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's mention of "top-N passages with character offsets and similarity scores" covers the return contract. The 200K truncation and truncation-flag behavior close the main edge case, making the tool self-contained for an agent.

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

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

Schema covers all three parameters with descriptions, so the baseline is 3. The description adds contextual framing: text is something already fetched (e.g., SEC 10-K), query is natural-language with examples. This enriches semantics beyond the schema, though limit remains schema-only.

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 "Semantic search INSIDE a fetched record," naming a specific verb and resource. It distinguishes itself from sibling research tools by focusing on a user-supplied text rather than external databases, and even names a companion tool (ask_pipeworx_grounded) to clarify its role.

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 "Use when the record is too big to cram into the prompt" and contrasts with the alternative by pairing with ask_pipeworx_grounded. This gives a clear condition and a fallback strategy, exceeding baseline.

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=false, idempotentHint=true, destructiveHint=false), the description discloses important behaviors: it requires a Pipeworx OAuth account, mentions that anonymous/BYO cannot persist, notes that SMS must be verified and has a 10/day cap, and indicates the feed is always on. These details add significant context without contradicting any annotation.

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

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

The description is well-organized into three sentences covering types, delivery channels, and requirements. Each clause provides necessary information without fluff. Given the tool's complexity, the length is appropriate and every sentence earns its place.

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 subscription creation tool with no output schema, the description covers all essential aspects: supported subscription types, parameter examples, delivery channels, authentication prerequisites, and the return of a subscription ID. It even references how to pull the feed, making it contextually complete for the target use case.

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 detailed descriptions for all three parameters, so the baseline is 3. The description adds semantic value by giving concrete examples like 'items:["5.02"] = officer change' and clarifying delivery behavior (e.g., SMS verification). However, the schema already covers most parameter meanings, so the extra value is marginal rather than substantial.

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

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

The description begins with 'Create a proactive monitoring subscription to a live-data event stream,' which specifies a clear verb and resource. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by describing the create action and listing supported subscription types. The inclusion of return value and examples further clarifies the tool's role.

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

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

The description provides clear context on when to use the tool, such as requiring a Pipeworx OAuth account and detailing allowed subscription types and delivery channels. It implies usage scenarios through examples and mentions how to pull the feed (e.g., via recent_alerts), but it does not explicitly state when not to use the tool or name alternative tools for specific cases. Thus, it falls short of an explicit exclusion/alternative list.

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, and idempotentHint, so safety is covered. The description adds meaningful behavioral context: it returns category-bucketed examples, draws from a live catalog, and supports optional topic filtering. It doesn't mention response limits or pagination, but that's minor.

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 segment serves a purpose: example queries, output description, parameter usage, and when-to-use guidance. It is front-loaded with natural language queries. Slightly dense but not wasteful.

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 moderate complexity (one optional parameter, no output schema, rich annotations), the description is complete: it explains what it returns, when to use it, how to call it, and what the topic parameter does. An agent would know exactly when and how to invoke this tool.

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

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

Schema coverage is 100% for the only parameter, so the schema already documents 'topic' well. The description adds examples and clarifies the 'omit' behavior, but this is marginal beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. It distinguishes itself from siblings by focusing on 'what can I ask' and mentioning specific categories and meta-tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' providing clear usage context. It also explains how to call with or without a topic. It doesn't explicitly contrast with alternatives like discover_tools, so it's not a perfect 5.

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

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

The description discloses key behavioral traits beyond annotations: ownership enforcement (only your own subscriptions) and the non-destructive nature (row deactivated, not deleted, with historical events preserved). This complements the annotations (idempotent, non-destructive) and adds meaningful context for the agent.

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 action, and every clause adds value. It explains what happens (deactivation) and the consequence (history via recent_alerts) without redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete. It covers purpose, usage constraints, and side effects, while annotations handle safety. No gaps remain for the agent to infer.

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 covers 100% of parameter semantics, including the id description 'Subscription id (uuid) returned by subscribe.' The description only mentions 'by id' without adding new meaning, which meets the baseline but does not elevate it.

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

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

The description clearly states the tool's function with a specific verb ('Cancel') and resource ('subscription by id'). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the cancellation action and the deactivation behavior, which is a unique 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?

The description provides clear context on when to use this tool: to cancel a subscription you own. It also implies the alternative of using recent_alerts for historical data after cancellation. Does not explicitly name alternatives or when-not-to-use conditions, but the context is sufficient for a single-purpose tool.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description adds rich behavioral context: the two distinct processing paths, the meaning of 'could_not_verify' (check did not happen, carries an error, must not be treated as evidence) vs. 'unsupported' (looked but no source), and the promise of verbatim evidence with pipeworx:// citations. This gives the agent essential insight into edge cases and failure semantics.

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

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

The description is a single dense paragraph, but it is front-loaded with trigger phrases and covers multiple necessary aspects (routing, outputs, caller warnings). It is longer than ideal but every sentence contributes substantive information, and the complexity of the tool justifies the length. It could be broken into clearer bullet points, but it is efficiently written.

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 absence of an output schema, the description is remarkably complete. It explains what the tool does, when to use it, the two processing paths, the exact verdict values, the response format (value, citation, reasoning), and crucial caveats about 'could_not_verify' and 'unsupported'. The agent can confidently invoke this tool and interpret its results without additional context.

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

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

The input schema already provides 100% parameter coverage, including detailed explanations for both 'claim' and 'tolerance_pct'. The description adds no new parameter-level meaning beyond what the schema states; it merely references the tolerance concept in passing. Per rubric, a baseline of 3 is appropriate when schema coverage is high and description adds no extra parameter detail.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources, with specific trigger phrases ('fact check', 'verify the claim that…'). It distinctly differentiates from siblings by focusing on verifiable truth claims and returning a structured verdict, and it explicitly contrasts the financial (SEC/XBRL) and general grounded pipelines. The description names concrete output types and cites its role as a replacement for multi-step workflows.

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 directly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies routing behavior for financial vs. other claims and notes efficiency ('Replaces 4–6 sequential calls'). However, it does not explicitly name alternative sibling tools or state when not to use this tool, so it lacks explicit exclusions.

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