Ship On Friday

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

Annotations declare the tool read-only, idempotent, and non-destructive. The description goes beyond by explaining the default model is free, that passing '_apiKey' triggers external Anthropic calls with user-paid costs, and the return structure includes per-model score, confidence, signals, and raw response. This provides valuable behavioral context not captured in annotations.

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

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

The description is compact at three sentences, front-loads the core purpose, and includes no redundant information. It efficiently conveys the tool's function, models, and typical use cases.

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 the tool's input, output structure, and typical applications. However, it omits potential error scenarios (e.g., invalid API key, model unavailability) and rate limits. Given the richness of schema descriptions and annotations, the description is nearly complete but could benefit from mentioning these edge cases.

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

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

Schema coverage is 100% with all parameters described. The description adds meaning beyond the schema by explaining the default model rationale ('free'), that '_apiKey' is passed straight through to Anthropic, and that 'context' helps disambiguate. This enriches the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about a given entity and scores visibility per model. It uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility (0-100) per model'), distinguishing it from siblings that focus on different tasks (e.g., 'scan_competitor_ai_presence' for competitors).

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 when the tool is useful ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), but does not explicitly state when not to use it or compare it to sibling tools like 'scan_competitor_ai_presence'. The guidance around API key and models is clear, but lacks exclusions or alternatives.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description adds behavioral details: routes to internal tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and works on every tier with one fast call. It does not disclose failure modes or limitations, but the core behavior is adequately transparent.

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

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

The description is longer than average but well-structured with a strong opening directive and logical flow. There is some redundancy between 'PREFER OVER WEB SEARCH' and the later 'Use whenever' phrasing, but the example list and alternative tool guidance earn their place.

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

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

For a broad routing tool with no output schema, the description explains the return format (structured answer with citation URIs), when to use it (default entry point), tier compatibility, and explicit alternatives. It adequately covers usage scenarios and special cases like breaking news, making it a complete guide for selection.

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

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

Schema covers all 6 parameters at 100%, all aliases of 'question' with clear descriptions. The tool description supplements with concrete example queries ('current US unemployment rate', 'Apple's latest 10-K') and states the natural-language format, adding semantic context beyond the schema's alias list.

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 (routes, returns) and resource (5,529 tools across 1,455 verified sources), and clearly distinguishes itself from siblings by positioning as the default entry point and naming higher-tier alternatives (ask_pipeworx_grounded, deep_research). It goes beyond a generic 'answer questions' by detailing the routing and citation behavior.

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

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

Explicitly instructs to prefer this over web search for enumerated domains, lists trigger phrases ('what is', 'look up', 'find'), and provides 'Step up only when needed' guidance for alternatives. It also tells when not to step up (e.g., breaking news is handled here), giving clear boundaries.

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

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

Goes well beyond annotations by disclosing the experimental nature, the possibility of live candidate improvements, the current inactive state, and that it is a full working router. This adds critical temporal and reliability context not available from annotations alone.

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

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

The description is front-loaded with the core identity ('Beta version of ask_pipeworx'), and every sentence contributes essential information: current status, usage, comparison purpose, and reassurance of full functionality. It is concise without being terse.

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 the beta nature, current routing state, usage, and comparison role. It does not specify the response shape directly, but it refers to ask_pipeworx's identical response shape, which is acceptable given the tool's purpose. No output schema exists, but the description provides enough context 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?

The input schema already provides 100% coverage with detailed descriptions for each alias and the main 'question' parameter. The description only says 'same arguments' without adding new semantic details, so it adds little 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 that this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It differentiates from siblings by explicitly positioning it as the 'experimental edge' and mentions the comparison with the stable router.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also describes the current state (no active candidate) and notes that results are compared against the stable router, clearly implying when to use this vs. the stable alternative.

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

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

Description adds substantial behavioral context beyond annotations: it details the return shape ({answer, evidence, confidence, ...}), lists specific refusal_reason enums, and notes the extra LLM call cost. Annotations (readOnlyHint, idempotentHint) are consistent and the description enriches transparency without contradiction.

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

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

The description is information-dense but well-organized, front-loading the core purpose and then detailing return behavior, usage, and cost. Every sentence adds value; no fluff or repetition.

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

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

Despite no output schema, the description fully explains return values and error/refusal cases. It covers use cases, alternatives, cost, and behavioral guarantees, making it complete for a high-stakes grounded lookup tool.

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

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

Schema description coverage is 100%, so the schema fully documents the single 'question' parameter and aliases. The description adds no additional parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode that routes like ask_pipeworx, fetches data, and extracts answers using only the tool result. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and direct alternatives: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off, making the decision 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 mark the tool as readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral detail: fan-out patterns, resolver contract, safety mechanisms (low-confidence blocking, closed market handling), spread warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is long but well-structured: it starts with a clear one-line summary, then uses sections (classifiers, fan-out examples, response shapes, resolver contract, safety). It is front-loaded with the core purpose. While verbose, the complexity of the tool justifies the length; every section adds value.

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

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

Given the tool's complexity (3 params, no output schema), the description is remarkably thorough. It covers all key aspects: market resolution, fan-out logic, response fields, edge cases (low confidence, closed markets, wide spreads), cancellation rules, and safety mechanisms. This compensates well for the lack of an output schema.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by explaining how to use the market parameter (slug, URL, question text) and the depth/raw options, but the schema already provides adequate detail, so the description adds minimal extra semantics 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 a Polymarket bet by pulling Pipeworx data in one call. The verb 'research' and specific resource 'Polymarket bet' make the purpose explicit. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on comprehensive data gathering and analysis.

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

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

The description provides explicit usage examples: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. However, it lacks explicit guidance on when not to use this tool (e.g., when to use sibling tools instead), though the context makes it fairly 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 indicate read-only, open-world, idempotent, non-destructive. Description adds details: for companies, pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, pulls FAERS adverse events, FDA approvals, trial counts. Results sorted by primary metric. 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?

Front-loaded with trigger phrases and core function. Packs much information into one sentence but could be slightly more structured for readability. Still efficient with minimal 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?

Given 2 parameters and no nested objects or output schema, description covers entity types, data sources, sorting, and citation URIs. Output format could be more explicit (e.g., structure of paired data), but overall complete for expected use.

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

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

Schema coverage 100% with descriptions. Description enriches by explaining what data each type returns (company vs drug), gives examples for values (tickers, drug names), and notes off-calendar fiscal year handling. Adds significant meaning beyond schema.

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

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

Description clearly states tool does side-by-side comparison of 2-5 companies or drugs in one parallel call, with explicit trigger phrases like 'Compare X and Y' and 'X vs Y'. It distinguishes from siblings by recommending over sequential single-pack lookups, addressing sibling tools like entity_profile.

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

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

Provides explicit when-to-use guidance: comparison, ranking, head-to-head. Says 'ALWAYS PREFER over sequential single-pack lookups' and mentions replacing 8-15 lookups, giving clear context for use cases.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds rich operational detail: the findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], semantic excerpting instead of head-truncation, hop fields, and latency expectations. It also discloses that citations are only present when the source can serve them.

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

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

The description is long (~250 words) but heavily dense with operational and usage context, beginning with the account prerequisite and using attention-grabbing clarifiers like 'this is NOT open-web search'. Some repetition about contradictions and hopped behavior exists, but the structure is logical and front-loaded.

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

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

With no output schema, the description fully covers return values and behavioral expectations: the findings packet structure, gaps[] for unanswered facets, contradictions[], citation_uri resolvability, semantic excerpting, and latency. It also covers account, payment, and alternative-tool usage, making the description complete for this complex tool.

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

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

Schema coverage is 100% for both parameters, but the description adds semantics beyond the schema: question accepts broad/multi-part input because decomposition is the point, and depth variants are tied to hop/recovery/paywall behavior, with time expectations. This goes beyond the baseline for high 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 clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains decomposition into facets. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, and provides concrete example questions.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also notes account/payment prerequisites and names the fallback 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?

Adds context beyond annotations by describing the return format (top-N tools with full schemas) and that results are ready to call directly. 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?

Well-structured single paragraph, but the long list of example domains could be trimmed for conciseness; still informative and front-loaded.

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

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

Given the tool's role as a discovery tool, the description is complete: it defines purpose, output shape, and usage context. No output schema but explanation suffices.

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 reinforces usage but does not add significant new meaning beyond the schema for each parameter, though it contextualizes the overall purpose.

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

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

Clearly states the tool finds tools by describing data or task, and distinguishes it from siblings by being the discovery tool for browsing available tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear usage context, though no explicit when-not-to-use or alternatives are given.

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, so the safety profile is covered. The description adds useful behavioral details: soft-failing patents (USPTO API sunset), specific return fields, and URI construction. 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 slightly verbose. It includes many examples and details that are helpful, but could be tightened. Front-loads purpose well. Still earns a 4 for being well-structured despite length.

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

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

Given the tool's complexity (multiple data sources, fallbacks, specific return fields) and absence of output schema, the description is remarkably complete. It covers what is returned, how URIs are formed, and known limitations (patents soft-fail). No gaps for the intended use case.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema: explains that value must be ticker or zero-padded CIK, names not supported, and type enum currently only 'company'. This provides clarity that the schema alone does not.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, lists specific sources and return fields, and distinguishes from sibling tools like resolve_entity. The examples ('Tell me about X', 'research Acme') make the purpose immediately understandable.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use: names are not supported, so use resolve_entity first. This provides clear guidance on selecting this tool versus alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing 'sensitive data' but does not elaborate on other behavioral aspects like irreversibility or error handling. Given annotations, the description provides moderate added value.

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

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

The description is three concise sentences: action, usage conditions, and pairing advice. Every sentence adds value, and the most important information is front-loaded in the first sentence.

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, single-parameter tool with annotations (destructiveHint, idempotentHint) and no output schema, the description covers the essential behavioral and usage context. The pairing recommendation with 'remember' and 'recall' completes the picture.

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 the schema describing 'key' as 'Memory key to delete'. The description echoes this and adds context about the key referencing a 'previously stored memory', but does not significantly extend the schema's meaning.

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

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

The description clearly states the tool's purpose: 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and a well-defined resource (memory by key), and distinguishes it from siblings like '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?

The description provides explicit usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also suggests pairing with 'remember' and 'recall', but does not explicitly state when not to use this tool or contrast with alternative tools beyond the pairing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral details: fetches page, extracts title/description/key links, emits markdown format. This context complements the annotations without contradiction.

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

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

The description is concise (3 sentences) and front-loaded with the primary action. The 'Useful for' section adds context efficiently. Minor redundancy in 'production-ready' but 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 only 2 simple parameters and no output schema, the description explains the output format (markdown blob ready to drop at site-root/llms.txt). It covers the essential usage scenario but omits error handling or limitations, which are not critical for this straightforward 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% (both url and max_links described). The description mentions 'any URL' and 'maximum number of link entries' but does not add significant new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt file), and purpose (for AI crawlers). It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on llms.txt generation.

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

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

The description explicitly lists use cases (getting a client's site indexed, drafting for own project, auditing competitor), providing clear context on when to use. However, it does not explicitly state when not to use or compare with siblings, leaving some implicit 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details by listing return fields and implying read-only behavior. No new side effects or constraints are disclosed 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 consists of two concise sentences: first stating purpose and return fields, second offering usage guidance. No unnecessary words; information is front-loaded and efficient.

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

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

Despite having no output schema, the description lists key return fields and explains usage context. The single optional parameter is well-documented. Given the tool's simplicity and rich annotations, the description is adequately complete.

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

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

Schema coverage is 100% with a clear description for the only parameter (include_inactive). The description does not add additional meaning beyond what the schema provides, so baseline score of 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists the return fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by noting usage for review before adding or canceling.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use scenarios. It implies context (before subscribe/unsubscribe) but does not explicitly exclude other uses.

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 rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token mechanism for tracking feedback, and the fact that the team reads digests daily. These details go well beyond the annotations, which are all false, and set clear expectations for the tool's behavior.

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

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

The description is longer than average, but every sentence earns its place: purpose, usage criteria, exclusions, claim_token flow, rate limit, and cost. It is well-structured and front-loaded with the core purpose, making it efficient despite its length.

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

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

For a feedback tool with no output schema, the description covers the key aspects: what it does, when to use it, how claim_token works, and limits. It could mention the exact response format, but it already tells users what to expect (claim_token, status, changes). Overall, it is complete enough for an agent to use effectively.

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 all four parameters with complete descriptions (100% coverage), so the description need not repeat them. The description does add value by clarifying claim_token usage (pass it alone with no other arguments) and advising to describe issues in terms of Pipeworx tools/packs, but the schema already does the heavy lifting.

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

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

The description starts with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource and clearly states the tool's purpose. It also distinguishes itself from sibling tools by emphasizing feedback for Pipeworx tools only, not other MCP servers.

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

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

The description explicitly states when to use the tool (bug, feature/data_gap, praise) and when not to use it ('if the tool came from a different MCP server... file it with that server instead'). It also provides criteria for identifying Pipeworx tools, making the usage guidance unambiguous.

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

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

Annotations already include readOnlyHint, openWorldHint, etc. Description adds valuable context: derived from CF analytics-engine, no PII, caching behavior, and response structure.

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

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

Two sentences plus a bullet list. Front-loaded with a hook (‘What other AI agents are calling...’). No wasted words; every sentence earns its place.

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

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

Given one parameter and no output schema, description explains what is returned (top tools, packs, call volumes) and caching behavior, making it fully informative.

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

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

Single parameter with full schema coverage. Description adds value by explaining that shorter windows surface hot items and longer windows show steady-state demand.

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

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

Description clearly states it returns trending tools, packs, and call volume over a window, distinguishing it from siblings like discover_tools by focusing on current popularity.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, aligning use case). No when-not or alternatives are mentioned, but context is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder rejection), fill check against live CLOB depth, and response structure. No contradictions with annotations. This extra transparency justifies a 5.

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

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

The description is relatively long and dense, but it is front-loaded with the main purpose and uses clear sections (mode explanations, semantic anchor, partition filter, fill check). Given the complexity of the tool, the length is justified, though some sentences could be shortened. Still very well-structured, so a 4.

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

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

Despite no output schema, the description fully explains the response structure: opportunities array with gap_pp, suggested_trade, reasoning, monotonicity context, and for event mode, partition_check details. It also covers fill check behavior. The description is self-contained and complete for an agent to use correctly, earning a 5.

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

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

Schema coverage is 100% with both parameters described. The description adds significant meaning: event accepts slugs or full URLs, topic is a seed question with examples. It explains how each parameter affects the tool's behavior (single-event vs cross-event). This adds value beyond the schema, earning a 5.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args for trending scan, event for specific market, and topic for cross-event scan. This specificity and differentiation from sibling tools earns a 5.

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 each parameter: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. It explains the benefits of cross-event mode and warns about partition filter and fill check conditions. This provides clear usage guidance with exclusions and alternatives, earning a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Beyond these, the description adds extensive behavioral context: it details the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), explains caching (1h at KV level keyed on all knobs), describes the response structure including diagnostics, and clarifies the limitations of fed_candidates. There is no contradiction with annotations.

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

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

The description is extremely lengthy and packed with details, which is helpful for understanding but harms conciseness. It is structurally organized with paragraphs and lists, but it could be more front-loaded and trimmed to essential information 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 (9 parameters, 3 model families, no output schema), the description is remarkably complete. It explains the response structure (by_segment, diagnostics), the tradeable-edge knobs, caching behavior, and even limitations (fed_candidates excluded). All aspects relevant for an agent to use the tool correctly are covered.

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

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

With 100% schema coverage, the baseline is 3. The main description adds extra meaning by explaining the context and rationale for key parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly, which complements the already detailed schema descriptions. This goes beyond mere parameter listing.

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: scanning top Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It also specifies its intended use case ('what should I bet on today'). However, it does not differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which have overlapping functions.

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 by stating 'Built for what should I bet on today' and highlights discovery without paging many markets. However, it does not provide explicit guidance on when to use this tool versus its siblings, nor does it mention when not to use it or list alternatives.

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

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

Annotations already cover read-only, idempotent, not destructive. The description adds important behavioral details: how decay is computed (from daily closes, not intraday), response structure including tracked, expired, snapshot_dates, and gaps in snapshot data. 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 long but front-loaded with the core question. It contains useful detail on response format and limitations, but could be more concise. Every sentence adds value, but overall length is high.

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 thoroughly explains the return structure (tracked, expired, snapshot_dates) and edge cases (gaps, TTL). It addresses the complexity of the tool well.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: days default 14 max 30, window default '1wk', and explains their role in snapshot lookback and family. This adds meaningful value.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily polymarket_edges snapshots. It distinguishes from sibling tool polymarket_edges by focusing on time-series analysis and answering 'how long has this edge existed and is it shrinking?'

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 provides context for when to use: to distinguish between a fresh wide edge and an old wide edge. It mentions limits like 60-day snapshot TTL and that snapshots run on cache-miss. While it doesn't explicitly say when not to use, 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 the tool read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it walks the order book ladder, checks against live depth, identifies forced directional risk, and warns that partial basket fills convert an arb into an unhedged position. No contradiction with annotations exists.

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

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

The description is front-loaded with the core purpose and then breaks into well-structured sections for single-market and basket modes. Although it is detailed, every sentence adds value, and the use of bold headers aids readability. It trades some brevity for completeness, which is justified by the tool's complexity.

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

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

Given no output schema, the description lists all returned fields for both modes, including verdicts and risk indicators. It covers the complete semantics: single-market returns fill details and slippage; basket returns aggregate and per-leg information along with forced directional risk. This allows the agent to fully understand and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description enriches parameter meaning beyond the schema. For example, it explains how size_usd is interpreted differently for buys vs. sells and how basket mode uses settlement notional. The description also clarifies the auto-detection logic for side in basket mode. While helpful, it does not cover every edge case, so a score of 4 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 starts with a clear, specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It then details two modes (single-market and basket) with distinct behaviors, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges. The purpose is unambiguous and well-defined.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' providing clear when-to-use guidance. It also explains why (theoretical overround not capturable, partial fills create directional risk), effectively directing the agent away from inappropriate 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?

Goes beyond annotations by explaining internal logic (compatibility_warning conditions, skipped leg counters, temporal alignment check). No contradiction with annotations; readOnlyHint/ idempotentHint align with described 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?

Well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS), but slightly long due to thoroughness. Each sentence adds value, though brevity could be improved.

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?

Extremely complete given no output schema: covers input modes, output structure (leg prices, spread, compatibility_warning, temporal_alignment, skipped counters), edge cases, and behavioral notes. No gaps remain.

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

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

Adds meaning beyond schema descriptions by explaining mode interaction, listing exact topic values, and clarifying how explicit parameters override topic. Examples in schema complement 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 it computes cross-venue spread between Kalshi and Polymarket, specifies two modes (topic and explicit), and details output format. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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, including pre-mapped shortcuts, explanation of safety fields (compatibility_warning, temporal_alignment), and caveats about real spreads being rarer than shortcuts. It helps users interpret results correctly.

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

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

Annotations already provide safety profile (readOnlyHint, etc.). Description adds scoping detail and pairing with remember/forget, 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, no wasted words, front-loaded with main action. Efficient and 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?

Tool is simple with one parameter and no output schema. Description fully covers purpose, usage, scope, and sibling relationships.

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 clear description. Description adds minimal extra meaning beyond schema: omitting key lists all keys, which is also evident from examples.

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 value saved via remember or lists all keys if omitted. It uses specific verbs ('retrieve', 'list') and distinguishes from siblings (remember, 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?

Explicitly states when to use ('look up context stored earlier without re-deriving') and implies when not to (use forget for deletion). Also notes scoping by identifier.

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

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

Description reveals the tool can mark events as read (state change), contradicting the readOnlyHint annotation. Rule requires score 1 for 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?

Efficient and no fluff, but slightly dense and could benefit from clearer separation of param explanations.

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 main behavior, return fields, and key options, but lacks mention of limit and unread_only params (though schema covers them).

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 meaningful examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains mark_read behavior, exceeding baseline 3.

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

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

Clearly states it pulls fired events from subscription feed, but does not explicitly differentiate from sibling tools like list_subscriptions or subscribe.

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?

Mentions polling works and an alternative REST endpoint, but does not guide when to use this tool over siblings.

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

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

Description adds significant behavioral context beyond annotations (readOnly, openWorld, idempotent, non-destructive): fan-out to multiple APIs, fallback logic, USPTO sunset soft-fail, return format with grouped changes and citation URIs. No contradictions.

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

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

Description is a single dense paragraph but front-loaded with usage examples and covers all aspects. Could be slightly more structured with bullet points, but every sentence earns its place.

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

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

Given 3 required params, 100% schema coverage, no output schema but description details return format, and annotations fully cover safety traits, the description leaves no gaps 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 coverage is 100%, and description adds meaning: explains `since` accepts ISO or relative shorthand with examples ('7d', '30d', '3m', '1y'), clarifies `value` can be ticker or CIK, and notes `type` only supports 'company' today.

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

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

Description clearly states it is a change feed for a company, fanning out to multiple specific sources (SEC EDGAR, GDELT→GNews, USPTO) and returns structured changes. It distinguishes from sibling 'entity_profile' by specifying 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?

Provides explicit query patterns ('What's new with X', 'latest on Y') and when-not-to-use: 'Use entity_profile instead when you want the static profile regardless of window.' Also explains fallback behavior (GDELT→GNews) and soft-fail for USPTO.

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 provide idempotentHint true and destructiveHint false. Description adds valuable context: storage as key-value pair scoped by identifier, and persistence duration (24h for anonymous, persistent for authenticated). Does not explicitly confirm overwrite behavior for same key, but overall good transparency.

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

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

Description is short (4 sentences), front-loaded with primary purpose, and every sentence adds value without redundancy.

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

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

For a simple key-value store tool with no output schema, the description fully covers usage context, persistence behavior, and relationships to sibling tools. No gaps identified.

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 has 100% coverage with descriptions for both parameters. Description adds extra context about scoping by identifier and examples that align with the key/value descriptions. Provides slight added meaning beyond schema.

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

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

The description clearly states the tool's function: saving data for later reuse across conversations or sessions. It provides specific examples (ticker, address, preference) and distinguishes itself from siblings recall and forget.

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

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

Explicitly states when to use (when discovering something worth carrying forward) and pairs with sibling tools (recall, forget). Also explains scope and persistence differences between authenticated and anonymous sessions.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds non-obvious behavior: identifiers are labelled with their source, unresolved identifiers are explicitly listed, enrichment degrades gracefully if GLEIF/OpenFIGI fail, and the tool cascades through endpoints internally. This goes well beyond the annotation hints.

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

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

The description is front-loaded with examples and a clear directive, then follows with structured details per type. It is longer than a two-sentence minimal description, but each sentence provides unique information. The sentence about cascading and replacing manual lookups is contextually valuable; no redundancy or fluff.

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

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

Despite lacking an output schema, the description thoroughly conveys what to expect: source-labelled identifiers, explicit unresolved entries, graceful degradation, and citation links for drugs. It also covers two entity types with their specific identifier systems, making it self-contained for complex usage.

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 meaning by specifying what each type returns (e.g., company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand) and clarifying accepted value forms with examples. This is valuable but the schema already covers the basic input semantics, so not a full 5.

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: resolving user-spoken names to canonical/official identifiers. It uses specific verbs and resources ('resolve', 'canonical identifiers', 'identifiers other tools require as input') and differentiates from siblings by instructing to 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicit usage guidance is provided: 'Use FIRST whenever you have a name but need an ID.' It also mentions that the tool replaces 2-3 manual lookups, which is context against alternatives. No direct exclusions are given, but the 'FIRST' directive clearly frames when to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that the tool probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density. No contradiction with annotations. The description complements annotations well.

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

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

The description is two sentences and a parenthetical example. The main verb and purpose are front-loaded. Every sentence adds value; no superfluous words.

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

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

Given the tool has 4 parameters (all documented), annotations covering safety, and no output schema, the description explains the process, entity ordering, and output shape. It is mostly complete but could briefly mention that the entities array limit (2-8) is enforced, though that's in the schema.

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

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

Schema description coverage is 100% (all parameters have descriptions). The description adds semantic value by stating that the first entity in the array is treated as the 'subject' for narrative and the rest as competitors. This provides usage-context beyond schema details.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally, and ranks them. It distinguishes from sibling tool ai_visibility_check (single entity) and compare_entities (general comparison) by specifying the use case for competitive AI-marketing audits.

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 'useful for competitive AI-marketing audits' and gives an example question, indicating when to use. It does not explicitly state when not to use, but the context implies using ai_visibility_check for single entity checks. A brief exclusion statement would improve 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?

Describes behavioral traits beyond annotations: fans out to external services, partial failures degrade gracefully, first measurement can take 5-30s, and sources_failed will list failures. No contradiction with annotations (readOnlyHint, openWorldHint, etc.).

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?

One dense paragraph, front-loaded with purpose, but every sentence adds value. Could be slightly more structured with bullet points, but is efficient and informative.

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

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

No output schema, so description fully covers return format (summary block, per-advisory detail, links, alternative versions) and partial failure behavior. This is complete for a composite data tool.

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

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

Schema coverage is 100% with clear descriptions. The description does not add significant meaning beyond the schema, just reiterates ecosystem (npm) and default behavior. Baseline 3 applies due to high 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 clearly states the tool's purpose: a composite check for adding npm packages, combining data from deps.dev and bundlephobia. It specifies the problem it solves ('should I add this npm package?') and distinguishes itself from siblings which are unrelated (e.g., AI visibility, 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?

Explicit usage guidance is provided: use when asking if a package is safe/popular/small, or what adding it costs. It also tells when not to use (for PyPI etc., use deps.dev:version directly) and mentions ecosystem limitations (npm only v1).

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 safe, read-only, and idempotent behavior. The description adds rich detail: BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char limit with truncation flag, and output includes offsets and scores. 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?

Single paragraph of 4-5 sentences, front-loaded with core purpose. Every sentence contributes meaningful information without redundancy.

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

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

No output schema, but description fully explains return values (top-N passages with offsets and scores). Also covers embedding details, windowing, and input limits. Comprehensive for a 3-parameter 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 provides 100% coverage of parameters with descriptions. The description adds context: 'Pass the text you already pulled' for text, example queries, and hints at limit range. This extra context justifies a score above baseline 3.

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

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

The description clearly states the tool performs semantic search inside a fetched record, saving context by returning only relevant passages. It mentions pairing with ask_pipeworx_grounded but does not explicitly differentiate from sibling search tools like ask_pipeworx or deep_research, which slightly reduces clarity.

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

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

Explicitly advises using when the record is too large for the prompt, and suggests pairing with ask_pipeworx_grounded. However, it does not provide when-not-to-use guidance or compare with alternative tools.

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

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

The description adds significant behavioral context beyond annotations: 'The answer is always no', 'Returns a rotating reason, risk level (always catastrophic), suggested day, and on-call sympathy score.' This explains the output behavior. Annotations already indicate safety (readOnlyHint, idempotentHint, destructiveHint false). 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 extremely concise with only three sentences. The purpose is front-loaded in the first sentence. Every sentence contributes value: purpose, answer, return fields. No wasted words.

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

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

Given the tool's simplicity and the presence of an output schema (not shown but indicated), the description adequately explains the tool's behavior. It lists the return fields and the constant answer. For a novelty check tool, this is complete.

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

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

The input schema has 100% description coverage for all 3 parameters (is_friday, team_size, deploy_type). The tool description does not add any additional meaning about these parameters beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Check whether you should ship on Friday.' It includes the specific verb 'check' and the resource 'shipping on Friday'. The humorous twist 'The answer is always no' adds clarity. It distinguishes itself from the many sibling tools by its unique function.

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

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

The description implies when to use (when considering shipping on Friday) and that the answer is always no, but does not explicitly state when not to use or provide alternatives. Given the tool's novelty and humorous nature, the implied usage 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?

Provides extensive behavioral details beyond annotations: requires OAuth, supported types, delivery channels, SMS cap, phone verification, webhook signing. Consistent with annotations (no contradiction).

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

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

Description is thorough but not overly long. Front-loaded with core purpose. Every sentence adds value, though some could be slightly more concise.

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

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

Given the complexity (3 params, nested objects, no output schema), the description fully explains all aspects: purpose, return value, prerequisites, types, delivery options, limits, and verification steps.

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

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

Schema description coverage is 100%, so baseline 3. Description adds significant context with examples and constraints for each parameter, such as required fields for each type and phone verification requirements.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. Verb 'create' and resource 'subscription' are specific. Distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Describes when to use (to subscribe to alerts) and prerequisites (requires Pipeworx OAuth account). Does not explicitly state alternatives, but the context of siblings implies 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 indicate read-only, non-destructive, idempotent behavior. The description adds valuable behavioral context beyond annotations: it describes the return format (category-bucketed example questions with exact tool+argument shape), the effect of calling with no arguments vs. a topic, and how it teaches usage of meta-tools.

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

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

The description is front-loaded with the key question and examples, but it is somewhat verbose. Each sentence adds value for an onboarding tool, but could be slightly trimmed without losing clarity. Still well-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's simplicity (one optional parameter, no output schema) and the presence of annotations, the description covers all necessary aspects: purpose, usage, input explanation, and return value. It is complete and leaves no gaps for the agent.

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

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

Schema coverage is 100% with one parameter described. The description adds meaning by explaining the parameter's effect: 'Call with no arguments for the full spread, or pass `topic` (e.g. "finance", "pharma") to focus' and lists example values, going beyond the schema description.

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

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

The description clearly specifies the tool's purpose as the onboarding entry point for learning what Pipeworx can do, returning category-bucketed example questions. It distinguishes itself from sibling tools like ask_pipeworx and discover_tools by explicitly stating its role and listing alternatives.

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 FIRST when you do not yet know what Pipeworx can do for you') and provides alternatives (ask_pipeworx, entity_profile, compare_entities). It also explains how to use the optional topic parameter to focus the response.

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 key behaviors beyond annotations: ownership enforcement, row deactivation rather than deletion, and preservation of historical events via recent_alerts. Consistent with annotations (destructiveHint false, idempotentHint true).

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 efficiently convey action, constraints, and side effects. No extraneous information; every word serves a purpose.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers all necessary aspects: what it does, ownership, behavioral effect, and relation to sibling tool. Complete for agent usage.

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 provides full coverage (100%) and parameter description. Description adds no additional semantic value beyond restating 'by id'. Baseline 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like subscribe (opposite) and recent_alerts (historical events preserved).

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 enforces ownership ('you can only cancel your own subscriptions'), providing clear context for when to use. The mention of deactivation (not deletion) guides against using it for full removal, though explicit alternatives are not named.

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, idempotent behavior, but the description adds significant context: the meaning of 'could_not_verify' (check did not happen) vs 'unsupported' (no source), and warns callers not to treat could_not_verify as evidence. It also details the two routing paths and the structured vs grounded pipeline behavior, going 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 long but well-structured, front-loaded with trigger phrases and organized into purpose, behavior, and caller warnings. Every sentence contributes useful information, though it could be trimmed slightly without losing meaning. It earns a 4 due to the density of valuable 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?

Despite no output schema, the description thoroughly covers return values (verdicts), citation format, and error semantics. It addresses the tool's complexity with two operational modes, explains failure handling, and provides enough context for an agent to use it correctly. Complete for the tool's 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% and both parameters have descriptions, but the description adds extra semantics: tolerance_pct overrides the implied tolerance, with an example of 'set 1–2 for hallucination detection,' and explains the default behavior (implied by wording, capped at 5). This adds value beyond the schema fields.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It provides trigger phrases and explicitly distinguishes between financial claims (via SEC EDGAR+XBRL) and other claims (grounded pipeline), making its scope unambiguous and differentiating it from siblings like 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?

The description says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use. It also notes it 'Replaces 4–6 sequential calls,' implying an efficiency advantage. However, it does not explicitly name alternative tools or give when-not-to-use conditions, so it falls short of a 5.

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