Materials

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by disclosing the default model (Workers AI Llama-3.3-70b), key requirement for Anthropic, and return structure (per-model {score, confidence, signals, raw_response}). 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?

Two sentences with clear front-loading: action, default behavior, optional key, response shape. No wasted words.

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

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

The tool has 4 parameters (100% described), no output schema, but the description summarizes return structure (per-model + combined view). Though it lacks details on 'raw_response', annotations provide safety profile. Completeness is adequate for 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%, baseline 3. The description adds meaning beyond schema: clarifies default model for 'models', explains when '_apiKey' is needed, and gives examples for 'entity' and disambiguation for 'context'. This extra 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 uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility'), distinguishing it from siblings like 'deep_research' or 'compare_entities'. It clearly identifies the tool's role in AI-marketing audits and brand checks.

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

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

The description explicitly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not provide explicit when-not-to-use or alternative tools. However, the context of sibling tools implies alternatives, and the guidance is clear enough for appropriate selection.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context beyond annotations: it routes to 5,529 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and mentions it works on every tier with one fast call. No contradiction.

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

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

The description is long but information-dense, front-loading the most critical guidance ('PREFER OVER WEB SEARCH') and structuring the rest into use cases, examples, and escalation paths. Every sentence contributes distinct value; it could be split into bullets for easier skimming but remains efficient.

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

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

For a complex routing tool, the description is remarkably complete: it covers what types of questions are appropriate, how the tool works (routing, filling arguments, citations), when to step up to alternatives, and provides multiple examples. Even without an output schema, the return behavior (structured answer with citation URIs) is disclosed.

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 100% of the 6 parameters (all aliases for 'question'), so the baseline is 3. The description provides example questions and clarifies the tool accepts natural language questions, but doesn't add new parameter-level semantics beyond what the schema already states.

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: routing factual questions to the right source among 5,529 tools and returning structured answers with citations. The verb 'routes' and resource 'question to the right tool' is specific, and it explicitly distinguishes from siblings like ask_pipeworx_grounded and 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 guidance: 'PREFER OVER WEB SEARCH for questions about...', 'START HERE for most questions', and 'Step up only when needed' for ask_pipeworx_grounded and deep_research. It also provides concrete examples of when to use, making alternatives clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds significant context: identical to ask_pipeworx, live candidate routing, current state (no active candidate), full working router with no fallback, and comparison against stable. This goes well 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 a single dense paragraph covering beta status, equivalence, routing behavior, usage, and fallback. Every sentence adds value, but it is slightly verbose and could be tightened without losing information.

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

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

Despite no output schema, the description explains the tool's experimental nature, current behavior, relationship to ask_pipeworx, and that it is a full working router with same response shape. This is complete for the tool's complexity.

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

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

Schema description coverage is 100% with clear descriptions for all 6 parameters (question and aliases). The tool description adds no param-specific detail beyond saying 'same arguments', 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 is a beta version of ask_pipeworx, a universal router with 5,529 tools, and explains its relationship to the stable counterpart. It distinguishes from siblings by noting candidate routing improvements and current equivalence to ask_pipeworx.

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

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

Explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions that results are compared against the stable router. It names the alternative (ask_pipeworx) but does not explicitly state when not to use it, so it lacks full exclusion guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds important behavioral context beyond annotations: the exact output structure (answer, evidence, confidence, source, fetched_at, refusal_reason:null), the refusal reasons (not_in_source, no_tool_match, etc.), and the extra LLM call cost. This helps the agent anticipate edge cases and error handling.

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

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

The description is somewhat long but well-structured: purpose, mechanism, output format, usage guidance, cost trade-off. Every sentence earns its place, but the full sentence about refund reasons could be slightly trimmed. Still highly informative without redundancy.

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

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

For a complex tool with no output schema, the description thoroughly covers return values, refusal modes, when to use, and relative cost. It also references the sibling ask_pipeworx and quantifies the tool universe (5,529 tools, 1,455 sources), providing complete context 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 schema has 100% coverage of all parameters, including the main 'question' field and its aliases. The description does not add parameter-specific details beyond 'fills arguments,' but the schema already documents these clearly. Baseline of 3 is appropriate since no additional meaning is needed.

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: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the mechanism (routing, fetching, extracting from tool result only) and distinguishes from sibling ask_pipeworx by emphasizing verbatim evidence and explicit refusals when the data doesn't answer.

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 gives when-to-use guidance ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when-not-to-use ('prefer ask_pipeworx for casual lookups'). It also names the alternative and notes the cost difference (one extra LLM 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?

The description goes far beyond annotations, detailing market resolution, fan-out logic, response shapes, safety mechanisms (low-confidence short-circuit, closed markets), tradeability warnings, and resolution-rule risk. It also warns agents to inspect match confidence before trusting analysis.

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

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

The description is very long and includes many sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.), which is informative but could be more concise. It front-loads the main purpose, but the length may be excessive for an AI agent.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers all relevant aspects: resolution confidence, parent events, news fallback, safety, closed markets, wide spreads, and cancellation rules. It leaves no gaps.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the 'market' parameter accepts slug, URL, or question text, and describes the effect of 'depth' and 'include_raw' defaults. This provides context beyond the schema.

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

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

The description clearly states the tool researches Polymarket bets using Pipeworx data, with specific verb and resource. It distinguishes from sibling tools like ask_pipeworx and polymarket_edges by providing use-case examples such as 'should I bet on X' and explaining the output structure.

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

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

The description gives explicit when-to-use examples and classifiers, but does not provide when-not-to-use or alternatives. The examples are comprehensive, but a brief exclusion note would improve clarity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: data sources (SEC EDGAR for companies, FAERS for drugs), fiscal year handling, result sorting, and citation URI inclusion. This enriches the agent's understanding of side effects and output characteristics without contradicting annotations.

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

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

The description is a single paragraph but front-loaded with example queries, which aids quick comprehension. Every sentence adds value: usage guidance, data sources, sorting behavior, and efficiency claim. While it could be slightly more structured (e.g., bullet points), it remains concise given the amount of useful detail.

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

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

Despite lacking an output schema, the description explains what the output contains (paired data + pipeworx:// citation URIs, sorted by primary metric) and how data is sourced and handled (fiscal year corrections). For a tool with only two non-nested parameters, this provides complete context for an agent to understand both input and output behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds semantic value by explaining what each type retrieves (e.g., 'type="company" pulls LATEST 10-K revenue + net income + cash + long-term debt') and gives concrete examples for values (tickers/CIKs for company, drug names). This goes beyond the schema's basic type and range constraints.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It uses specific verbs like 'compare' and identifies the resource (companies/drugs). It distinguishes from siblings by recommending preference over sequential single-pack lookups, which contrasts with 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 to prefer this tool over sequential single-pack lookups when comparing entities. It lists example queries that trigger the tool. However, it does not explicitly state when not to use it, though the schema constraints (2-5 values) and examples imply single-entity cases are handled by other tools.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail beyond annotations: account/sign-in requirements, paid tier for 'thorough', parallel decomposition, return format with gaps[] and contradictions[], never-invented guarantee, excerpting strategy, timing expectations, and citation_resolvability rules. 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?

Despite its length, every sentence earns its place: account prerequisites, sibling differentiation, decomposition strategy, return packet contents, gap handling, depth semantics, citation fetchability, and timing. It's front-loaded with the most critical operational constraint (account required) and organized into logical clauses 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?

With only 2 parameters, no output schema, and no nested objects, the description fully compensates. It explains the output format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), error/degradation behavior (gaps[], contradictions[]), performance expectations, and edge cases like current-news topics returning empty gaps. This 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?

Schema coverage is 100%, so baseline is 3. The description adds semantic value for 'depth' by explaining hop recovery and contradiction behavior for standard/thorough, and for 'question' by clarifying that broad/multi-part questions are the intended use case ('decomposition is the point'), which goes beyond the schema's minimal phrasing.

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 ('research') and resource ('Pipeworx's 1455 STRUCTURED data sources') with clear scope ('in ONE call') and explicitly distinguishes from siblings ('this is NOT open-web search'). It also names alternatives like ask_pipeworx, making the tool's unique 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 when-to-use guidance ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'), and names the fallback tool (ask_pipeworx). It also covers account-tier restrictions and depth-level choices.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable details: returns top-N tools with names, descriptions, and full schemas, and that results are ready to call without a second lookup. This informs the agent about the tool's behavior beyond the annotations.

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

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

The description is well-structured with the purpose stated upfront, followed by usage examples and return details. It is slightly verbose due to listing many domain examples, but each sentence adds value. It remains efficient 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?

For a tool discovery tool, the description fully covers its purpose, input (natural language query), output (top-N tools with full schemas), and usage context (call first). No output schema exists, but the description clearly explains what the agent receives. The information is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds value by providing concrete usage examples (e.g., 'look up FDA drug approvals') and clarifying that the query accepts natural language, enhancing the semantic understanding beyond the schema.

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

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

The description begins with a clear verb 'Find tools by describing the data or task', explicitly stating what the tool does. It distinguishes itself from sibling tools by positioning it as a discovery/browsing tool, not a task-specific tool like 'bet_research' or 'deep_research'.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set', providing clear context for when to use. It also lists example tasks (SEC filings, FDA drugs, etc.) to illustrate applicability, though it does not explicitly state when not to use.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context: it makes a parallel call, fans out across multiple sources, returns sorted data, and notes soft-fail for patents (USPTO sunset). No contradictions with annotations.

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

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

The description is somewhat lengthy but front-loaded with example queries and key guidance. Every sentence adds value, and the structure flows logically from purpose to usage to output details. Minor redundancy in parameter descriptions keeps it from a 5.

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

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

No output schema exists, so the description must explain return values. It does so thoroughly: CIK, company_name, recent_filings (with URIs), fundamentals (specific fields sorted), patents (with sunset warning), news, and LEI. Coverage of what the tool returns 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?

Both parameters have full schema descriptions (100% coverage). The description repeats the schema's info about ticker/CIK format and name requirement, but does not add new parameter-specific meaning beyond examples. 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 explicitly states that the tool provides a full cross-source profile of a US public company, listing specific data points (CIK, filings, fundamentals, patents, news, LEI). It differentiates from siblings by advising preference over chaining single-pack lookups and directing name-based queries to resolve_entity.

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

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

The description clearly states when to use this tool (for a holistic view) and when not (if only a name is provided, use resolve_entity first). It also specifies that it should be preferred over alternative multi-step lookups, offering explicit 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 destructiveHint=true and idempotentHint=true, so the description's disclosure adds limited value. The description confirms deletion but does not elaborate on side effects or reversibility.

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

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

Two sentences, front-loaded with the action, and includes usage guidance. No extraneous words.

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

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

For a simple tool with one parameter, full schema coverage, and sufficient annotations, the description covers purpose, usage context, and relationship with siblings. No gaps.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The description adds no new semantic information beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data'. Lacks explicit when-not-to-use but is sufficient for a simple tool.

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

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

Annotations (readOnly, idempotent, non-destructive) are present, and description adds the fetch/extract/emit process and output format. Does not mention potential limitations like rate limits or URL validation.

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 only: purpose, process, use cases. No redundancy, front-loaded with key 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?

Output format (single text blob) is described despite no output schema. Could mention error handling or URL validation, but sufficient for a simple generation tool.

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

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

Schema covers both parameters (url, max_links) with descriptions, so description adds no extra meaning. Baseline 3 is appropriate for 100% schema coverage.

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

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

Clearly states verb 'Generate', resource 'llms.txt file', scope 'for any URL', and distinguishes from sibling tools (none other produce llms.txt). Also lists specific 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?

Provides explicit use cases (client indexing, own project, competitor audit) but lacks when-not-to-use or alternative tools. Context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return fields and scope (caller's subscriptions) but doesn't contradict. With annotations, the added behavioral context is moderate.

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

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

Two sentences, front-loaded with purpose, every sentence adds value. No waste.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers purpose, usage, and return fields.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add information about the include_inactive parameter beyond what schema already provides.

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

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

Clear verb and resource: 'List the caller's active subscriptions.' Specifies return fields. Does not explicitly differentiate from siblings but is unambiguous.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides practical context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it returns structure IDs, formulas, elements, site count, and a link, and notes the data is computed with millions of entries. No contradictions.

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

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

The description is a single well-structured paragraph that front-loads the purpose, gives usage guidance, lists filtering options, and disambiguates from siblings. Every sentence is meaningful with no redundancy.

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

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

Given no output schema, the description explains return fields (id, formula, elements, site count, link) and mentions scale. The input schema is fully covered with examples and parameter descriptions, leaving no gaps.

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

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

Schema coverage is 100% with descriptions, so baseline is 3. The description adds some nuance (e.g., 'formula' normalized to OPTIMADE reduced form) but does not significantly surpass the schema. A score of 3 is appropriate.

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

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

The description clearly states the tool searches computed (DFT) crystal structures across multiple databases, specifying the verb 'Search' and the resource. It distinguishes from sibling tools like materials_stability and the COD pack for experimental structures.

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

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

The description explicitly recommends when to use this tool over web search for materials queries and provides specific use cases (element sets, exact formula). It also guides users away to sibling tools for experimental structures or stability data.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by detailing the computed nature and listing return fields (composition, formation energy, hull stability, band gap, etc.), which provides behavioral context beyond the annotations. No contradictions.

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

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

The description is concise and well-structured: it starts with the tool's main purpose, then gives usage guidance, parameter examples, and return schema. Every sentence adds value, with no wasted words.

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

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

Given the lack of output schema, the description adequately explains return fields and provides usage examples. It covers the essential aspects for a tool with 4 parameters and no nested objects. Minor omissions like default values or error handling are mitigated by the schema and annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description significantly adds meaning by providing examples (e.g., 'Fe, O' for elements, 'stable_only: true'), explaining parameter format, and clarifying the effect of 'stable_only'. This goes well beyond the schema alone.

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

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

The description clearly states the tool computes thermodynamic stability and formation energy from OQMD (DFT) for a chemical system, using a specific verb ('computed') and resource ('OQMD'). It distinguishes itself from web search with explicit use cases, making the purpose unambiguous.

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

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

The description explicitly recommends this tool over web search for specific queries like 'is <compound> stable' or 'formation energy of <material>', providing clear context for when to use it. However, it does not mention alternative tools within the sibling set, such as 'materials_search', which could be a comparable option.

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 rich behavioral context beyond annotations: explains the claim_token behavior ('Filing without an account returns a claim_token; pass it back later'), rate limits ('Rate-limited to 5 per identifier per day'), and that it is free, not counting against tool-call quota. This supplements the annotations (which are all false) and does not contradict 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?

Although longer than two sentences, each sentence earns its place: purpose, use cases, exclusions, claim_token mechanics, rate limits, and quota. The information is front-loaded with the core purpose and organized logically, making it easy for an agent 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?

No output schema exists, but the description covers return values ('returns a claim_token', 'Returns the status and, once resolved, what actually changed'). It also covers account behavior, rate limits, and exclusions, making it complete for a feedback submission tool with 4 parameters.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds extra meaning: for claim_token, it specifies how to use it ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and that it should be used with no other arguments. It also clarifies message length expectations (1-2 sentences typical).

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

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

The description states a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists feedback types (bug, feature, data_gap, praise) and distinguishes from siblings by clarifying it is for feedback about Pipeworx tools only, not for asking questions or getting data like the sibling ask_pipeworx or discover_tools.

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

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

Provides explicit when-to-use scenarios ('Use when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well'). It also gives clear when-not-to-use guidance: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). No contradictions.

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

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

Three sentences with bullet-pointed use cases. Front-loaded with the core purpose. Every sentence serves a purpose; 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?

The description explains what the tool returns (top tools, top packs, total call volume) and data freshness. With no output schema, a bit more detail on the exact structure (e.g., whether counts are included) would be helpful, but it's largely 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?

Only one parameter 'window' with 100% schema coverage. The description adds interpretive guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' enhancing the schema's enum values.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It provides three specific use cases (discovering hot data, confirming canonical choice, aligning use case), and the purpose is distinct from siblings like discover_tools.

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

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

The description gives explicit use cases and explains window selection (shorter for hot, longer for steady-state). However, it lacks explicit guidance on when not to use this tool or alternatives among the many sibling tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, confirming safe, non-destructive behavior. The description adds significant behavioral context: the internal checks (monotonicity, partition sum), semantic anchor (Jaccard similarity >=0.30), partition filter (dropping placeholder slugs), response structure, and the fill check that references live CLOB depth. This goes well beyond annotations to inform the agent about what happens during execution.

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

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

The description is long but well-structured with sub-headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and capital emphasis. It front-loads the main purpose and modes. However, some internal details like the Jaccard threshold and placeholder fraction could be condensed without losing clarity, making it slightly less concise than ideal.

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

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

Given the tool's complexity (multiple modes, internal logic, and structured response), the description is remarkably complete. It explains the response fields (opportunities[], partition_check fields), the fill check mechanism, and even references polymarket_fill_risk for custom sizing. Without an output schema, the description fully compensates by describing the return format, so the agent understands what to expect.

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

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

Both parameters (event, topic) have schema descriptions, yielding 100% schema coverage. The description adds substantial meaning: it explains that event can be a slug or full URL, topic is a seed question, and provides examples for both. It also details mode-specific behavior, such as how topic searches related events and flattens markets, which is not captured in the schema alone.

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

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

The description clearly states the tool's purpose: to find arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, and the verb 'Find' combined with the resource 'arbitrage opportunities' makes the purpose unambiguous. This 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?

The description gives explicit guidance on when to use each mode: no args for a trending scan, event for a specific market (recommended), and topic for cross-event scanning. It explains why cross-event mode is useful (catches patterns missed by single-event) and directs users to polymarket_fill_risk for custom sizing, providing an alternative. This makes selection and invocation clear.

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

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

Annotations declare readOnlyHint true, and the description adds extensive behavioral details: model families, edge net of slippage, Kelly fractions, 24h-move warning, diagnostics. No contradiction.

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

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

The description is lengthy but well-structured with sections and bullet points. It front-loads the purpose but could be slightly more concise without losing value.

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

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

Despite no output schema, the description details return structure (by_segment, fed_candidates, diagnostics) and caching behavior. It is fully informative given the tool's complexity.

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

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

Schema coverage is 100%, and the description adds meaningful context for each parameter (e.g., min_partition_leg_kelly explanation, slippage_pp defaults).

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and specifies three segments. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 targets 'what should I bet on today' and mentions tradeable-edge knobs. However, it lacks explicit guidance on when not to use this tool versus alternatives like polymarket_arbitrage.

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

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

The description goes beyond annotations by detailing data source limitations (60-day TTL, snapshot start), computation details (daily closes, not intraday), and response structure. No contradiction with annotations.

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

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

The description is well-structured but somewhat lengthy. It front-loads purpose and then details response and limits. Could be slightly more concise, but every sentence adds value.

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

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

For a tool with no output schema, the description thoroughly explains response fields (tracked, expired, snapshot_dates) and their meanings, plus data source and limitations. Complete and self-contained.

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 description adds context: default values, max for days, and purpose of window parameter. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay from daily snapshots. It uses specific verbs ('track', 'answers') and distinguishes itself from the sibling tool 'polymarket_edges' which likely provides raw snapshots.

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

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

The description implies usage for understanding edge longevity and decay, but lacks explicit when-to-use vs alternatives or exclusions. The context is clear but could be more direct.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: walks the order book ladder, returns fill details and a verdict (clean|degraded|cannot_fill), warns about forced_directional_risk, and explains that partial basket fills convert an arb into an unhedged directional position. 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 somewhat lengthy but well-structured with clear sections for single-market and basket modes, and includes a critical usage warning. It is front-loaded with the primary purpose. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is comprehensive. It explains both modes, the return values, the rationale for usage, and potential risks. An agent has all necessary information to correctly invoke this tool in the intended 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 description coverage is 100%, and the description adds meaning beyond the schema: it explains the default behavior for 'side' (auto for basket), clarifies the interpretation of 'size_usd' for each mode (max spend vs target proceeds vs settlement notional), and provides usage context for event and market parameters. This significantly aids correct parameter selection.

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 specifies the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and lists specific outputs (top_of_book, vwap_fill_price, slippage_pp, etc.), effectively differentiating it from sibling tools 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?

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale—theoretical overround on thin books is not capturable and partial fills cause directional risk—and provides clear prerequisites (requires market or event).

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

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

Goes far beyond annotations (readOnlyHint, etc.) by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) and explaining conditions that make spreads invalid. 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 thorough but somewhat verbose, containing multiple sentences that could be consolidated (e.g., repeated warnings about pre-mapped topics). However, it is well-structured with clear sections and front-loaded purpose.

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

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

Despite lacking an output schema, the description fully explains the response structure, including raw probabilities, spread calculations, and every safety field. Covers edge cases and limitations thoroughly for a cross-venue spread 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% and each parameter is described in the schema. The description adds value by explaining the two modes, listing specific topic values, and providing example tickers, but does not add new parameter-level information beyond what the schema already documents.

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

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

Description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question, specifies two modes (topic shortcuts and explicit tickers), and is distinct from sibling Polymarket tools like polymarket_arbitrage that focus on single-venue opportunities.

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 on when spreads are meaningful (equivalent bet shapes) and warns that most pre-mapped topics return compatibility warnings, discouraging naive use. Lacks direct naming of alternative tools but gives sufficient context for appropriate invocation.

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?

Consistent with annotations (readOnly, idempotent, non-destructive) and adds scoping context. Does not mention potential error cases but annotations already cover safety.

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

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

Two sentences, fully front-loaded with purpose and usage, 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?

Adequately covers purpose, usage, scoping, and pairing. Lacks explicit error conditions but acceptable for a simple retrieval tool with robust annotations.

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

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

Schema coverage is 100%, so baseline is 3. Description adds scoping context but does not significantly extend the schema's parameter 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 retrieves a saved value or lists all keys when omitted, explicitly distinguishing from siblings 'remember' 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 a clear use case ('look up context stored earlier') and scoping information, though it does not explicitly state when not to use it.

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

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

The description discloses that setting mark_read:true flags events as read, implying a mutation. However, annotations declare readOnlyHint=true, indicating no write side effects. This contradiction undermines transparency and could mislead an 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 concise (3-4 sentences), front-loaded with the purpose, and every sentence adds relevant detail without fluff.

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

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

The description covers most operational aspects (return fields, filtering, mark_read side effect, polling, alternative endpoint) but the annotation contradiction creates ambiguity about side effects, reducing completeness for correct 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 descriptions cover all 5 parameters (100% coverage). The description adds value by explaining mark_read's side effect, providing an example for type, and specifying ISO timestamp for since. It does not mention limit or unread_only, but the extra context improves understanding.

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

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

The description clearly states it pulls fired events from a subscription feed and returns recent alerts with specific fields. It distinguishes from siblings like list_subscriptions by focusing on event retrieval rather than subscription management.

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 context for usage: filtering by type and since, setting mark_read, and notes that polling works fine and an alternative endpoint exists. It does not explicitly exclude alternatives but gives enough context for typical use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant context: it makes one parallel call to multiple sources, describes fallback behavior (GDELT->GNews), mentions USPTO soft-failure, and outlines the return structure (changes[] grouped by source with pipeworx:// URIs).

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

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

The description is somewhat long but every sentence contributes useful information. It is front-loaded with example queries. Minor redundancy could be trimmed, but overall it is efficiently structured.

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

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

Given the tool has three required parameters, no output schema, and annotations indicating safety, the description provides complete context: data sources, fallback mechanism, parameter formats, return structure, and limitations. An agent can confidently invoke this tool based on the description alone.

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 parameters with descriptions, but the description adds value by providing usage examples for the since parameter (e.g., '7d', '30d', '1y'), clarifying that type is currently limited to 'company', and explaining that value can be a ticker or CIK.

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

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

The description starts with concrete example queries, then clearly states it is a change feed for a company within a time window. It lists specific data sources (SEC EDGAR, GDELT->GNews, USPTO) and distinguishes itself from the sibling tool entity_profile by noting when to use that instead.

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

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

The description explicitly tells when to use the tool (for 'what's new' queries) and when not to (use entity_profile for static profile). It provides guidance on the since parameter format (ISO date or relative shorthand) and typical values like '30d'.

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

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

Beyond annotations (idempotentHint, destructiveHint), the description adds scoping by identifier, persistence differences for authenticated vs anonymous sessions, and retention duration (24 hours). No contradictions.

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

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

Four sentences, efficiently conveying purpose, usage, behavior, and related tools. No unnecessary words; front-loaded with key information.

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

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

Given a simple key-value store with no output schema, the description covers all necessary aspects: purpose, when to use, behavior, and relationship to sibling tools. Complete and self-contained.

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

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

Schema already covers both parameters with descriptions. The description adds value by providing concrete examples (e.g., 'subject_property', 'target_ticker'), enhancing usability.

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 ('Save') and resource ('data'), and clearly distinguishes from sibling tools like recall and forget by mentioning them as paired operations.

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

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

Provides clear usage scenarios ('discover something worth carrying forward') with examples, but lacks explicit when-not-to-use guidance. Still above average.

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

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

The annotations already declare readOnly/openWorld/idempotent, but the description adds significant behavioral details: it cascades through multiple endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, labels identifiers with their source, and explicitly reports unresolved identifiers. This goes beyond the annotations, giving agents a clear model of failure modes and output composition.

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 well-organized: it opens with example queries to signal intent, then states the core purpose, breaks down supported types, and closes with degradation behavior and efficiency. Every sentence contributes unique information, and the formatting keeps it compact for the amount of detail.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: it lists the specific identifiers returned from each source (SEC EDGAR, GLEIF, OpenFIGI, RxNorm) and the behavior for unresolved or degraded sources. It also covers both entity types and the internal cascade, providing a complete picture for an agent to invoke the tool correctly.

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

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

The schema already provides 100% coverage of the two parameters, but the description enriches them further by clarifying accepted input forms (ticker, CIK, or company name for company; brand or generic for drug) and describing the output structure for each type. It adds detailed context about what will be returned for each parameter combination, exceeding the baseline for full schema coverage.

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

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

The description uses the specific verb 'resolve' with the resource being user-spoken names to canonical identifiers, distinguishing itself from siblings by stating these are identifiers 'other tools require as input.' It enumerates supported types and the exact identifiers returned (CIK, LEI, FIGI, RxCUI), making the scope unmistakable.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance, and it explains that it replaces 2-3 manual lookups. However, it does not explicitly name alternative tools or state when not to use it beyond the implied 'if you already have an ID,' 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.

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, covering core safety. The description adds behavioral details beyond these: it probes each entity with ai_visibility_check, returns a ranked list with score, confidence, and signal density, and treats the first entity as the subject. This enriches understanding without contradicting annotations.

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

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

The description is two concise sentences plus a parenthetical example, front-loading the core action and then providing context. Every sentence adds value with no fluff, making it efficient for an AI agent 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 no output schema, the description adequately explains the return value: a ranked list with score, confidence, and signal density. Combined with annotations (readOnlyHint, etc.), the description covers usage, parameters, and behavior, making the tool fully understandable for an AI agent.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful value by explaining that 'entities' should have the first entry as the subject and provides examples for 'context'. This goes beyond the schema descriptions, which are already clear.

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: compare AI visibility across multiple entities side-by-side using ai_visibility_check, rank by score, and identify most/least recognized. It provides a specific use case example and distinguishes itself from sibling tools like ai_visibility_check.

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

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

The description explains when to use this tool ('useful for competitive AI-marketing audits') and implies not to use it for single-entity checks by referencing ai_visibility_check. It does not explicitly list when not to use or direct to alternatives, but the context is clear.

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

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

Annotations already declare safe read-only behavior. The description adds that bundlephobia's first measurement can take 5-30s and that partial failures are handled gracefully with sources_failed. No contradictions.

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

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

The description is a single paragraph but is well-organized and front-loaded with the main purpose. Every sentence adds value; could be slightly more structured but remains clear.

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?

Without an output schema, the description fully details the return fields (summary block, advisory details, links, alternatives) and failure behavior. Covers inputs, outputs, constraints, and ecosystem scope.

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%. Description adds context: scoped packages accepted for 'package', and version defaults to latest if omitted. This goes beyond schema basics.

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

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

The description clearly states the tool performs a composite check for adding npm packages, combining deps.dev and bundlephobia data. It is distinct from sibling tools, which focus on other domains (e.g., AI presence, 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?

Explicitly mentions use cases: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also states NPM-only in v1 and points to deps.dev directly for other ecosystems.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds technical details: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars with truncation flag), and output features (character offsets, similarity scores). These go beyond annotations to inform agent of limitations and behavior.

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

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

Four sentences, each carrying essential information: purpose, use case, paired tool, technical implementation details. Front-loaded with the core action. Zero redundant or irrelevant content.

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

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

Covers all necessary aspects for an agent: what the tool does, when to use it, how it works technically (embeddings, windows, truncation), output format (passages with offsets), and relationship to sibling tools. Although no output schema, the description adequately describes return values.

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% (3 params all described). Description provides concrete examples for 'text' (SEC 10-K) and 'query' (supply-chain risk, drug interactions). For 'limit', it mentions 'top-N passages' implicitly. This adds value beyond the schema's descriptions.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' and specifies the verb (search) and resource (a record's text). It distinguishes itself from siblings by explaining it is for sub-document retrieval and explicitly pairs with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt'. Describes alternative approach (grounding over passages vs. whole document) and names a sibling tool (ask_pipeworx_grounded) for the complete workflow.

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 substantial behavioral details beyond annotations: requires OAuth, phone verification for SMS, 10/day SMS cap, webhook HMAC signing, and auto-disable after 10 failures. Annotations indicate idempotency and non-destructive nature, which the description does not contradict.

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 that front-loads the core purpose and then systematically covers types, delivery options, and constraints. It is efficient for the complexity but could benefit from slight structuring (e.g., bullet points or separate sections).

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

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

The description fully covers all parameters (type, params, delivery) with detailed sub-parameters, return value (subscription ID), prerequisites (OAuth account, phone verification), and edge cases (SMS cap, webhook failures). No output schema exists, but the description sufficiently explains what to expect.

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 enriches the schema by providing concrete examples for each subscription type (e.g., sec_8k with items, fred_series with series_id). The schema already has 100% coverage, so the description adds valuable usage examples without being redundant.

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

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

The description explicitly states the tool creates a proactive monitoring subscription, returns the subscription ID, and distinguishes itself from siblings like list_subscriptions and unsubscribe by specifying it is for creating new subscriptions.

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

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

The description provides clear context on when to use the tool: requires a Pipeworx OAuth account, describes supported subscription types with examples, and mentions delivery channel constraints. However, it does not explicitly contrast with alternatives like list_subscriptions or unsubscribe.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral details like drawing from a live catalog of thousands of tools and returning exact tool+argument shapes, but these are more feature descriptions than behavioral restrictions or side effects.

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

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

The description is fairly long but front-loaded with alternative phrasings and structured logically. Every sentence contributes useful information, though a slight reduction in length could improve conciseness.

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

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

Given the single optional parameter and no output schema, the description adequately explains what the tool returns (category-bucketed example questions with tool+argument shapes) and its role in onboarding. It also references meta-tools to connect with the broader tool ecosystem.

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

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

Schema coverage is 100% and the schema already describes the 'topic' parameter well. The description adds value by listing example values for the topic and explaining the behavior when omitted (cross-category spread), which goes beyond the schema's description.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by positioning itself as the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly says when to use it ('when you do not yet know what Pipeworx can do' and 'Use this FIRST'). It also mentions that calling with no arguments gives the full spread and passing a topic focuses the results. However, it does not explicitly state when not to use it or provide alternative tools for specific scenarios beyond the meta-tools 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?

Discloses that the row is deactivated (not deleted) and historical events remain via recent_alerts, adding important context beyond annotations. No contradiction with annotations.

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

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

Two sentences, no fluff, front-loaded with action and key constraint. Every sentence provides value.

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

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

Covers essential aspects: what it does, ownership constraint, behavior (deactivate vs delete), and relation to recent_alerts. Sufficient for a simple 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 already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' with 100% coverage, so description adds no additional meaning.

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

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

Clearly states 'Cancel a subscription by id' with specific verb and resource. Ownership enforcement distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement, indicating when to use (own subscriptions) and when not to. Could be more explicit about context, but provides good 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 goes well beyond the readOnly/openWorld/idempotent annotations by explaining the nuanced semantics of verdicts: could_not_verify means the check did not happen and is not evidence, unsupported means no source found, and it discloses the verification_error field. This is critical behavioral context that annotations alone don't 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 long but efficiently structured: trigger phrases, purpose, routing logic, return semantics, and error semantics. Each section earns its place, though it is somewhat dense and could optionally be tightened by moving some examples elsewhere.

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

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

Given the tool's complexity and the absence of an output schema, the description fully enumerates verdicts, the error scenario, and the evidence/citation behavior. It provides enough operational detail for an agent to invoke the tool correctly without additional documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that tolerance_pct overrides the implied tolerance and defaults to a cap of 5, and by illustrating claim formats. This extra nuance raises the score above baseline.

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

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

The description clearly defines claim verification against authoritative sources with a specific verb ('verify') and resource. It opens with natural-language trigger phrases, distinguishes between financial and non-financial claims via distinct pipelines, and enumerates the verdict types returned, making it unmistakable from sibling tools like 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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use context. It also details routing for company-financial vs. other claims. However, it doesn't name alternative tools for related but distinct needs (e.g., exploratory research), leaving some exclusions implicit.

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