Dostuff

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

Annotations already provide readOnlyHint and idempotentHint. The description adds: default model (Workers AI), optional Anthropic with BYO key, payment note, and return structure (per-model + combined). No contradictions.

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

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

Two sentences plus use-case summary. Every sentence adds information without redundancy. Front-loaded with purpose, then details. 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?

Despite no output schema, the description describes return format (per-model fields + combined view). It could detail error handling or scaling, but covers core expectations well. Annotations cover safety.

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 good descriptions. The description adds value by noting default model, the need for _apiKey with Anthropic, and the purpose of context. This goes beyond the schema.

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

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

The description clearly states it probes LLMs for knowledge and scores visibility (0-100). It specifies the verb 'Probe' and resource 'LLMs for entity awareness'. However, it does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, so it is not 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 implies usage context (AI-marketing audits, pre-launch checks, competitive monitoring) but lacks explicit when-to-use vs alternatives or when-not-to-use. It provides some guidance but no exclusions.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context: automatic routing to the right sub-tool, argument filling, stable pipeworx:// citation URIs, one fast call, and coverage of every tier. This goes well beyond the annotations, revealing how the tool behaves internally and what the user gets back.

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

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

The description is fairly long but well-structured: it front-loads the key directive, then uses example triggers, a list of domains, and explicit alternative-tool guidance. Every sentence contributes value, though it could be tightened without losing critical context.

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

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

Despite lacking an output schema, the description explains the return format structured answer with citations, covers when to use it versus siblings, and provides a wide range of example queries. It fully equips an agent to decide whether to invoke this tool and how to phrase the question.

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

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

The schema has 100% coverage with all six parameters as aliases for 'question'. The description reinforces meaning with concrete examples ('current US unemployment rate', 'Apple's latest 10-K') and clarifies the parameter accepts a natural-language request. This adds practical guidance beyond the schema's generic description.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and clearly states the tool routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with citations. This defines a specific verb-resource pair (answers factual questions) and distinguishes it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly provides when-to-use instructions: 'START HERE for most questions' and 'Use whenever the user asks ...' plus trigger phrases like 'what is', 'look up', 'find'. It also states when to step up to alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.'

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?

Explains the beta/experimental nature, the absence of an active candidate as of 2026-07-26, and that it currently matches ask_pipeworx exactly. Adds that it's a full working router with no fallback, beyond what annotations provide. Does not contradict the readOnly/idempotent hints.

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

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

Description is a single, well-structured paragraph that front-loads the beta status and includes all essential context: current behavior, usage, and experimental purpose. No redundant or filler content. Could be slightly more concise but is appropriately sized.

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 the tool's purpose, current state, usage guidance, and experimental role. Since the output schema is absent, the mention of 'same response shape' as ask_pipeworx provides sufficient expectation. Annotations already cover safety, so the description is complete for this beta variant.

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 six parameters documented as aliases for question. Description adds no additional parameter semantics but references 'same arguments' as ask_pipeworx, reinforcing that only question matters. Baseline of 3 is appropriate given comprehensive schema.

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

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

Clearly identifies as a beta variant of ask_pipeworx with the same universal router, tool set, arguments, and response shape. Distinguishes from sibling ask_pipeworx by highlighting the experimental routing improvements. The specific verb 'ask' is implied through the reference.

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 to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router. It implies ask_pipeworx is the stable alternative but doesn't explicitly say 'use the stable version for production'. Context is clear enough for an agent to choose.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the refusal mechanism with specific reasons, the evidence quote requirement, and the 'using ONLY what the tool result contains' constraint. It also mentions the extra LLM call cost, adding significant behavioral context.

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

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

The description is dense but well-structured: purpose, mechanism, return format, usage guidance, and cost trade-off are all covered with no filler. Every sentence contributes value, and the most important information is front-loaded.

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

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

No output schema exists, but the description fully explains return values on success and failure, including refusal reasons. It also covers routing scope, use cases, and cost. For a tool with this complexity, the description is remarkably complete.

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

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

Schema covers 100% of parameters (all are aliases of 'question' with descriptions). The description does not add new parameter-level meaning, but it doesn't need to since the schema is fully self-explanatory. Baseline 3 is appropriate.

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

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

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts') and resource ('tool result'). It distinguishes from sibling ask_pipeworx by highlighting the grounded extraction and refusal behavior, making its purpose unique.

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 (answers that will be quoted, cited, or acted on, high-stakes facts) and when not to (casual lookups, prefer ask_pipeworx). Also notes the extra LLM call cost, providing clear trade-off 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 indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral details: low-confidence resolution short-circuits, closed market handling, wide spread warnings, cancellation rules, news fallbacks, parent event extraction. No contradiction with annotations; description significantly supplements 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 but well-organized, starting with the core purpose and then detailing classifiers, fan-out examples, response shapes, and edge cases. While comprehensive, it could be slightly more concise. However, the front-loading of key information aids usability.

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 explains return field shapes (market, analysis, evidence, resolver contract, parent_event, news fields) and covers edge cases like low-confidence matches, closed markets, and wide spreads. Given the tool's complexity, this is highly 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?

All three parameters have descriptions in the schema. The tool description adds contextual examples for 'market', explains 'quick' vs 'thorough' for 'depth', and clarifies the purpose of 'include_raw' (summary vs full payload). This adds meaning beyond the parameter descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and what it does (resolve, classify, fan out, return evidence + comparison). This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides classifiers and fan-out examples. Does not explicitly mention when not to use, but the context is clear and siblings cover related tasks.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details: handling of off-calendar fiscal years, sorting by primary metric, return of paired data and citation URIs, and parallelism. This goes beyond the annotations.

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

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

The description is moderately lengthy but every sentence adds value. It starts with user-facing examples and then details technical behavior. While compactness could be improved, there is no wasted text.

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 simplicity of the input schema (2 parameters, no output schema), the description covers all necessary context: entity types, data pulled, sorting, return format (paired data + citation URIs), and parallelism. It is fully self-contained.

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

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

Schema coverage is 100% with both parameters described. The description enhances this by explaining the type-specific data (e.g., 'company pulls LATEST 10-K revenue...') and providing concrete examples (e.g., '["AAPL","MSFT"]'). This adds significant meaning beyond the schema.

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

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

The description clearly states that the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' with specific verbs and resources. It distinguishes itself from sequential lookups and is likely distinct from the 'entity_profile' sibling tool.

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

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

The description provides explicit example queries ('Compare X and Y', 'which is bigger') and a strong recommendation: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This gives clear guidance on when to use and implies alternatives for single-entity queries.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: account requirements and paid tier, parallel decomposition, findings-packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), gaps[] and contradictions[] fields, hop semantics, semantic excerpting, latency expectations, and the guarantee that citations are always fetchable. No contradiction with annotations.

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

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

The description is long but every clause earns its place by providing actionable info (auth, alternatives, decomposition, output structure, failure modes, latency). It is front-loaded with purpose and alternatives. Slightly stream-of-consciousness and repetitive in places (e.g., multiple mentions of NOT open-web search), but the density justifies 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 complex tool with no output schema, the description fully explains return values (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), behavioral nuances (hops, gap recovery, excerpting), prerequisites (account), alternatives, and performance expectations. Nothing significant is left unexplained.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaningful depth-specific behavior (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with iterative hop plus contradictions[]), enriching the depth parameter beyond the schema's enum text. The question parameter is self-explanatory and receives no additional semantic confusion.

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

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

The description clearly identifies the tool as a multi-source structured-data research tool: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with 'decomposes your question into focused facets... routes each to the right one of 5,529 tools IN PARALLEL.' It explicitly distinguishes itself from open-web search ('this is NOT open-web search') and from sibling tools by name (ask_pipeworx for single lookups/breaking news).

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It also names alternatives with clear when-not-to-use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Additionally, it provides account-tier prerequisites ('If you are not signed in, use ask_pipeworx instead').

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing that results include names, descriptions, full schemas, and are ready to call directly. No contradictions.

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

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

The description is a single paragraph that front-loads purpose and usage. The list of domains adds length but remains useful. Every sentence adds value, though it 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 100% schema coverage, detailed annotations, and no output schema, the description sufficiently explains tool function and return format. It is complete enough for effective 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 is 100%, so the description adds little beyond what the schema already provides (e.g., default limit, aliases). It does not enhance parameter meaning significantly.

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 tools by describing data or task, with a specific verb and resource. It lists many domains and distinguishes itself from sibling tools by being a first-call for discovering options.

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

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

The description explicitly says when to use the tool (browse, search, look up, discover) and advises calling it first when many tools are available. It does not explicitly state when not to use it or list alternatives, but the context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial context: data sources, return fields, limits (5 filings), sorting, fallback (GDELT→GNews), and patent API deprecation with soft-fail behavior. 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 moderately long but front-loaded with example queries and a clear purpose. Every sentence adds critical information, though it could be slightly more compact without losing value.

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

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

Given the complexity (multiple data sources returned, no output schema), the description comprehensively explains what is returned, constraints (only US public companies, name unsupported), and edge cases (patents soft-fail, news fallback). 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by reinforcing that only 'company' is supported for type, and for value, specifying that names are not allowed and providing examples (ticker or zero-padded CIK). This goes slightly beyond the schema descriptions.

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

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

The description explicitly states it returns a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from siblings by recommending it over chaining individual lookups and noting that 'resolve_entity' should be used for names.

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

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

The description clearly states when to use ('when the user asks for a holistic view') and when not ('names not supported — use resolve_entity first'). It also specifies that it must be preferred over multiple single-pack lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, so the description adds value by explaining concrete behavior: defaults to today, sorted by start time, and filtering options. No contradiction with annotations. The description is transparent and complementary.

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, with three front-loaded sentences covering purpose, default behavior, windowing, and optional filters. Every sentence adds unique value and there is 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?

Given 6 parameters, 100% schema coverage, no output schema, and safe annotations, the description covers the essential behavioral and usage context. It omits details like pagination or response format, but for a read-only list tool, it is sufficiently complete for correct invocation and interpretation.

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

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

Schema coverage is 100%, so the description's role is reduced. However, it adds useful semantics beyond the schema: 'defaults to today', 'cover a window (e.g. a weekend)', and enumeration of valid categories (music, art, etc.). This enhances the agent's understanding of parameter usage.

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

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

The description clearly states it returns 'curated things-to-do / events for a DoStuff metro' and specifies default behavior, date windowing, category filtering, and sorting. It effectively distinguishes from siblings like 'metros' (which lists metros) and other search tools, making the purpose unambiguous.

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

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

The description provides clear context on when to use: defaults to today, can cover a window with date/days, optional filters (category, free_only). It implies usage for event discovery. However, it does not explicitly state when not to use or name alternative tools, leaving slight room for confusion among the many sibling tools.

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

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

Annotations already label destructive and idempotent. Description adds minimal extra behavioral context beyond confirming deletion. Does not explain error handling or side effects.

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

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

Two concise sentences, front-loaded with core purpose. Every sentence adds value.

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

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

Simple tool with one parameter, good annotations. Description covers purpose, usage context, and sibling relationships adequately.

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

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

Schema covers 100% of parameters with a description. Description does not add new meaning beyond the schema's 'Memory key to delete'.

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

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

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

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

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

Provides specific usage scenarios: when context is stale, task done, or clearing sensitive data. Lacks explicit when-not-to-use instructions but is otherwise clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it fetches the page, extracts title/description/key links, and outputs a text blob, providing extra behavioral context beyond annotations.

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

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

Concise and well-structured: first sentence states purpose, second details process, third specifies output, fourth lists use cases. No wasteful sentences.

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

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

For a simple tool with 2 parameters and no output schema, the description covers purpose, process, output format, and use cases comprehensively. Annotations provide safety context.

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

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

Schema description coverage is 100%; both parameters are fully described in the schema. The description does not add new semantic meaning beyond what the schema provides, scoring 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 the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and target audience (AI crawlers). Distinguishes from siblings by focusing on a specific output format.

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 use cases like getting a client's site indexed, drafting own llms.txt, auditing competitor visibility. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds the return fields and default behavior (active only), providing additional useful context beyond annotations.

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

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

Two concise sentences with no fluff. The first defines the action and output, the second provides usage guidance. Front-loaded with essential information.

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

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

For a simple tool with one optional parameter, no output schema, and rich annotations, the description covers purpose, return fields, default behavior, and usage context. It is fully 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%, so the schema already describes the 'include_inactive' parameter and its default. The description implies the default (active subscriptions) but doesn't add new semantic meaning beyond the schema.

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

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

The description clearly states the action (list), resource (subscriptions), and scope (caller's active). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for the tool's utility.

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, idempotent, non-destructive. Description adds that it returns slug and name, no contradiction. Provides context that output feeds events tool.

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?

Extremely concise with two sentences, no filler, front-loaded with 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 zero parameters and no output schema, description fully explains tool's function and how to use its output. No gaps.

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

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

No parameters; schema coverage is 100%. Baseline 4 applies; no additional parameter info needed.

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

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

Description uses specific verb 'List' and resource 'metros DoStuff covers' with details (slug + name). Also distinguishes from sibling tools by mentioning usage with 'events' tool.

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

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

Clearly states the tool lists available metros and suggests passing slug to events tool for further use. Could explicitly mention when not to use, but good overall.

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 limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), asynchronous behavior ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and impact ('team reads digests daily and signal directly affects roadmap'). These behavioral traits go far beyond the sparse annotations (readOnlyHint=false, destructiveHint=false).

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 packs many essential details into a single readable paragraph without fluff. It is longer than average but every sentence earns its place (use cases, exclusions, claim-token mechanism, rate limits, cost). Only minor tightening could improve it, so a 4 is appropriate.

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

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

The tool has no output schema, but the description covers what a feedback tool needs: how to frame feedback, which reports are accepted, the async claim-token flow, and operational constraints. Together with the detailed parameter schema, this is fully sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds value by contextualizing claim_token ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and by instructing users to describe issues in terms of Pipeworx tools rather than pasting end-user prompts, which clarifies the message parameter. This extra context warrants a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback categories (bug, feature/data_gap, praise), which clearly distinguishes it from sibling query/research tools like ask_pipeworx or discover_tools.

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

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

It explicitly states when to use ('Use when a tool returns wrong/stale data...') and when not to ('ONLY for tools served by this Pipeworx connection... file it with that server instead'), plus a disambiguation test ('Not sure? Pipeworx tool names are the ones this connection lists'). This is textbook guidance with exclusions and alternatives.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description adds caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII). This enriches the agent's understanding of performance and data origin.

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 efficient: three sentences with bullet points, front-loading the core action. No extraneous words, every sentence serves a purpose.

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

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

For a simple read-only tool with one optional parameter, the description covers purpose, use cases, behavior, and basic output. While no output schema exists, the return values (top tools, top packs, volume) are mentioned. The caching and data source add depth. Slightly lacking on output format details.

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 descriptive enum and purpose for each window. The tool description only repeats the window options, adding no new semantic value beyond the schema.

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

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

The description uses a specific verb 'Returns' and clearly states the resource: top tools, top packs, and total call volume over a window. It distinguishes itself from siblings like 'discover_tools' by focusing on trending usage data.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case with demand). It lacks explicit exclusions or alternative recommendations but provides clear context for when 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, idempotent, open-world, non-destructive. Description adds significant behavioral detail: scanning top 200 markets, partition_check logic (sum of YES prices ~1, gap >3pp triggers signals), semantic anchor (Jaccard similarity >=0.30), partition filter (placeholder slugs, >20% placeholder returns null). Discloses fill check and what response contains. 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 lengthy (multiple paragraphs) but well-structured: starts with summary, then explains each mode, details on semantic anchor and partition filter, response format, and fill check. Every sentence adds value given complexity. Slightly verbose but justified; 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?

Despite no output schema, the description thoroughly documents the response structure (opportunities array with gap_pp, suggested_trade, reasoning, monotonicity context; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade; fill check fields). Covers multiple modes, edge cases (placeholder filtering), and provides warnings (do not trade if realizable_edge_pp <= 0). Fully informed for an AI agent.

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

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

Schema descriptions already cover both parameters (event slug/topic), but the description adds essential context: explains event slug format (accepts full URLs), topic as seed question, and the behavioral difference between modes. It also clarifies that passing no arguments triggers a default trending scan. Schema coverage is 100%, but description goes beyond to fully explain semantics.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args (trending_scan), event (single-market), and topic (cross-event). This specificity differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly explains when to use each parameter: no args for trending scan, event for a specific market with slug/URL, topic for cross-event scanning. Provides recommendations ('event recommended') and warns about fill check with realizable_edge_pp <= 0 meaning 'do not trade'. References sibling tool for custom sizing.

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, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral details: model families, edge calculation, caching (1h), Fed bets exclusion, and diagnostic output. 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 verbose and includes detailed model specifics (e.g., alpha values, placeholder-slug filters) that could be shortened. However, it is well-structured with clear sections and front-loaded purpose. Could be 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?

With 9 parameters and no output schema, the description fully compensates by detailing the response structure (by_segment, fed_candidates, diagnostics) and caching behavior. The complexity is well-covered, leaving no major gaps.

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

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

Schema coverage is 100% with clear parameter descriptions. The main description provides context for knobs like min_liquidity and max_spread_pp but does not add new meaning beyond what the schema already states. Baseline of 3 is appropriate.

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

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

The description states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies three segments (model_driven, structural_arbitrage, concentrated_longshot) and distinguishes itself from siblings like polymarket_arbitrage by focusing on edge detection.

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 it's built for 'what should I bet on today' and that agents can discover opportunities without paging. Provides context for when to use (discovery, edge identification) but does not explicitly state when not to use or compare to alternatives like polymarket_edge_tracker.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds detailed behavioral info: response structure (tracked, expired, snapshot_dates), decay computation on |edge_pp_net| signed by direction, limits (60-day TTL, no intraday). No contradiction with annotations.

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

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

Description is informative but somewhat verbose. However, every sentence adds value, and it is front-loaded with the key question. Structure is clear with separate sections for response fields.

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 format, including fields like edge_pp_net, trend, decay_pp_per_day, expired items with lifespan. Limitations are also 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?

Schema covers all parameters with descriptions (100% coverage). The description adds default values and clamp ranges, which are useful beyond the schema. Baseline 3 plus extra value yields 4.

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 edge persistence and decay telemetry from daily snapshots, answering the specific question 'how long has this edge existed and is it shrinking?'. It differentiates from siblings like polymarket_edges which likely provides current edges.

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

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

The description gives clear context for use: to assess edge age and decay. It implies when to use via the contrast between fresh and old edges, but does not explicitly mention when not to use or alternatives.

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

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

Annotations (readOnly, idempotent, non-destructive) already indicate safety, but the description adds critical behavioral context: walks the order book ladder, returns specific fields (top_of_book, vwap, slippage, etc.), and warns that partial basket fills convert an arb into unhedged directional risk—the dominant loss mode. No contradiction with annotations.

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

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

The description is long due to complexity, but every sentence is information-dense and earned. It front-loads purpose and requirements, and logically separates modes. Could be slightly more structured (e.g., bullet lists), but remains clear 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 high complexity and no output schema, the description exhaustively lists return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. This fully informs the agent about expected outputs.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the semantics of size_usd in basket mode ('settlement notional — shares per leg') and explaining the auto-default for side. These details go beyond the schema descriptions.

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

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

The description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explains two modes (single-market and basket). It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by advising 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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

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

Provides explicit when-to-use context: before acting on arb signals or trades above $500. Explains why partial fills cause directional risk and that theoretical overround is not capturable on thin books. Lacks exclusions for cases where the tool is not needed, but the threshold and signal context give clear guidance.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. Description adds significant behavioral context: two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explanation of when spreads are meaningless. 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 relatively long but well-structured: starts with purpose, then modes, then response format, then safety fields. Every sentence adds useful detail. Could be slightly tighter but remains clear and comprehensive.

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

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

No output schema exists, so description must detail return values. It does so thoroughly: covers each component of the response, explains rare conditions, and addresses edge cases. Provides sufficient information for an agent to correctly interpret results.

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

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

Schema coverage is 100% with brief descriptions. Description adds substantial meaning: defines each topic shortcut, explains explicit ticker overrides, and describes mode selection. Adds value beyond schema.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from sibling arbitrage tools by focusing on two specific venues and providing explicit modes. No ambiguity.

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

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

Provides clear contexts for use: comparing prices across venues, using topic shortcuts or explicit tickers. Explicitly warns that most pre-mapped topics return compatibility warnings and states 'pre-mapped ≠ tradeable'. Does not explicitly list alternatives, but context implies arb tools for single-venue.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping by identifier and mentions pairing, but no contradictions. Adds value beyond annotations.

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

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

The description is concise (3 sentences), front-loaded with purpose, and every sentence provides useful 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?

Given the simple key-value nature, the description, schema, and annotations provide complete coverage: safety (annotations), scoping (description), and usage (description). No output schema but return behavior is implied 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 description explains the effect of omitting the key (list all keys) and provides context examples (ticker, address), adding meaning beyond the schema.

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

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

The description clearly states the tool retrieves a value by key or lists all keys when omitted, distinguishing it from sibling tools 'remember' and 'forget' and providing concrete examples like ticker and address.

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 specifies when to use (look up stored context without re-deriving), how to list all keys (omit key), and pairs with remember/forget, offering clear guidance.

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

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

Describes return format and side-effect of mark_read, going beyond annotations. However, annotations claim readOnlyHint=true, conflicting with mark_read's state-changing behavior. The description is accurate and transparent about this, so it is scored highly; the contradiction is flagged separately.

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?

Concise, front-loaded, and every sentence serves a purpose. No redundant information. Structured logically from purpose to specifics.

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

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

For a tool with no output schema, the description adequately explains the return content. All parameters are covered, and the alternative endpoint is mentioned. The tool is simple and the description is sufficiently complete.

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

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

Schema covers all 5 parameters with descriptions. The description adds value by explaining how mark_read affects subsequent calls, that since expects ISO format, and that polling is safe. This exceeds the baseline of 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 pulls fired events from subscription feeds, specifies what each event carries (source, citation_uri, raw payload), and explicitly mentions filtering by type and since. It is specific and distinguishes from sibling tools by focusing on fired events.

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

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

Provides clear guidance on filtering, mark_read behavior, and polling suitability. Mentions an alternative endpoint for scripts/dashboards. Lacks explicit when-not-to-use instructions, but covers key usage scenarios.

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

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

Annotations already mark it as safe read-only/idempotent, and the description adds rich behavioral details: fan-out logic, fallback from GDELT to GNews, USPTO soft-fail, and relative date parsing, 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 dense but well-organized, front-loaded with examples, and each sentence adds necessary information. Slightly long but justified by 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 the tool's complexity (multiple data sources, fallback logic, no output schema), the description adequately explains the output structure, sources, and caveats, making it complete for an AI agent.

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

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

Schema covers 100% of parameters, but description adds value by explaining relative date shorthand, recommending '30d' or '1m', and clarifying value accepts ticker or CIK. Exceeds baseline of 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 provides a change feed for a company, with explicit usage examples like 'What's new with X'. It distinguishes itself from the sibling tool 'entity_profile'.

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

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

The description includes explicit when-to-use phrases and directly says 'Use entity_profile instead when you want the static profile', providing clear guidance on 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?

Description adds context beyond annotations: scope by agent identifier, persistence details (authenticated users get persistent, anonymous 24h). No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

For a simple store tool with good annotations and no output schema, the description is complete: explains purpose, usage, scope, and persistence. No gaps.

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

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

Schema coverage is 100%, but description adds examples of valid keys (e.g., 'subject_property') which adds meaning. Baseline 3, so 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 clearly states the tool saves data for reuse across sessions, with specific verb 'Save' and resource 'data as key-value pairs'. It distinguishes from siblings recall and forget by mentioning them as complementary tools.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and mentions not having to look it up again, providing clear context. Also advises pairing with recall/forget.

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 read-only, idempotent, open-world. The description adds rich behavior: identifiers labeled by source, unresolved identifiers explicitly stated under `unresolved`, graceful degradation when GLEIF/OpenFIGI unavailable, and internal cascading lookups. No contradiction.

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

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

The description is long but every section contributes value: example queries, supported types, and failure behavior. It is structured with a clear lead-in and organized sections, though it is more verbose than strictly necessary.

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 entity types, identifiers, sources, no output schema), the description thoroughly covers inputs, outputs, fallback behavior, and why it replaces multiple manual lookups. This is exceptionally 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 already covers both parameters with descriptions, so baseline is 3. The description adds meaning by enumerating acceptable formats for each type (ticker, CIK, name; brand/generic) and providing lookup examples, going beyond schema descriptions.

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

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

The description clearly states the tool resolves names to canonical/official identifiers, provides concrete example queries, and lists supported types. It differentiates itself from siblings by instructing to use it first when a name needs 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and gives example scenarios. It does not name specific alternative tools, but the trigger conditions are 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds behavioral details: probes each entity with ai_visibility_check, ranks, surfaces most/least recognized, returns score/confidence/signal density. Adds value beyond annotations without contradiction.

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

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

Two sentences front-load the main purpose, then detail behavior and use case. No redundant or unnecessary text. Every sentence adds value.

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

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

Despite no output schema, description explains return value (ranked list with score, confidence, signal density) and process (probes, ranks, surfaces). Covers all essential aspects given tool complexity and parameter richness.

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 3. Description adds extra meaning: 'First entry treated as the 'subject' for narrative; rest are competitors', which aids agent understanding. Also clarifies that models and _apiKey are optional and context disambiguates common names.

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 'Compare AI visibility across multiple entities side-by-side' with specific verb+resource. Distinguishes from sibling ai_visibility_check (single-entity) and compare_entities (generic comparison) by mentioning AI visibility, ranking, and competitive audit context.

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

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

Explicitly states use case: 'competitive AI-marketing audits: does Claude know about us as well as our competitors?'. Implies when not to (single entity check) by mentioning it probes multiple entities. Does not explicitly name alternatives but context is clear.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds critical behavioral details: partial failure graceful degradation, bundlephobia first measurement delay (5-30s), and sources_failed field. No contradictions observed.

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

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

The description is informative and well-structured, front-loading the core purpose. While slightly long, every sentence adds value (composite nature, tools used, behavior, use cases, limitations). Could be slightly more concise but still effective.

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

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

Given no output schema, the description comprehensively lists return fields (summary block, per-advisory detail, links, alternative versions) and explains graceful degradation. This fully compensates for the missing output schema.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context beyond schema, such as defaulting to latest version when omitted and the purpose of the version parameter in the composite check. A slight improvement over baseline.

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

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

The description clearly states this is a composite check for npm packages, combining deps.dev and bundlephobia data to answer whether to add a package. It specifically mentions the ecosystems and tools involved, distinguishing it from sibling 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 tells when to use (when asking about safety, popularity, size) and when not (other ecosystems like PyPI, Maven, etc., which use deps.dev:version directly). This provides clear guidance for the agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: embedding model (BGE-base-en), windowing (500-char overlapping windows), truncation (200K char cap with flagging), and return characteristics (offsets and similarity scores). 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 three sentences, each earning its place: purpose, usage guidance, technical details. It is front-loaded and contains no filler. Every sentence adds value.

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

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

Despite having no output schema, the description explains what is returned (top-N passages with character offsets and similarity scores). It covers truncation behavior, pairing with another tool, and embedding details. Given the tool's complexity, this is complete for selection and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra parameter meaning beyond schema descriptions (e.g., examples for query, default for limit). The technical details about embeddings and windows are context, not parameter-specific. Thus a score of 3 is appropriate.

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

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

The description uses a specific verb ('Semantic search INSIDE a fetched record') and clearly defines the resource and scope. It distinguishes from sibling tools by emphasizing that it operates on already-fetched records, contrasting with general search or grounding tools 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context'. It also provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document'.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds behavioral context beyond annotations: requires OAuth, returns subscription ID, delivery limitations (SMS 10/day cap, phone verification needed, webhook auto-disabled after failures). No contradiction with annotations.

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

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

The description is moderately long but well-structured with sections for types and delivery. Front-loaded with main purpose and prerequisites. Minor redundancy (e.g., sms constraints repeated) but overall efficient.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers purpose, prerequisites, type-specific parameters, delivery options with constraints, and behavioral details. It is sufficiently complete for an agent to use 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 with concrete examples (e.g., sec_8k: {ticker, items}) and constraints (e.g., sms must match verified phone, webhook https only). This adds value beyond the schema's property 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It names specific supported types (e.g., sec_8k, polymarket_edge) and delivery channels, differentiating it from sibling tools like unsubscribe and list_subscriptions.

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

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

The description explains when to use the tool (for proactive monitoring) and prerequisites (Pipeworx OAuth account, anonymous accounts cannot persist subscriptions). It provides examples of type-specific parameters and delivery options. However, it does not explicitly mention when not to use or compare to alternative tools, but given the niche functionality, this is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it returns category-bucketed examples with exact tool+argument shapes, drawn from a live catalog. 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 somewhat long but well-structured: it starts with natural language queries the user might type, then explains functionality and parameter. Each sentence adds value, though could be slightly trimmed.

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 low complexity (1 optional param, no output schema), the description adequately explains what the tool returns (category-bucketed examples with tool+argument shapes) and its role in onboarding. It is complete for its purpose.

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

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

Schema coverage is 100% with a detailed description for the 'topic' parameter. The tool description clarifies the optional nature and lists example focus areas, adding slight value beyond the schema.

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

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

The description states exactly what the tool does: returns example questions across categories to help users understand Pipeworx. It distinguishes from sibling tools like ask_pipeworx by explicitly positioning it as the onboarding entry point and recommending it be used first.

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

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

The description provides explicit guidance on when to use the tool (first time connecting, to learn capabilities) and how to invoke it (no arguments for full spread, optional topic for focus). It also tells users to use it before other meta-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?

Explains that the row is deactivated not deleted, preserving history. Annotations already provide destructiveHint=false and idempotentHint=true; description adds useful nuance about what happens to the data.

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, direct and front-loaded. Every sentence provides value with no filler.

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

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

For a simple one-parameter tool with good annotations, the description covers ownership, effect, and parameter origin completely. No gaps for an agent to use it correctly.

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

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

Schema provides 'id' with description 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' and implies the source, adding context beyond the schema.

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

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

Clearly states 'Cancel a subscription by id.' Distinguishes from sibling tools 'subscribe' and 'list_subscriptions' with specific verb and resource.

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 ownership is enforced and you can only cancel your own subscriptions. Does not specify when to use vs alternatives like 'list_subscriptions' or 'subscribe', but context is clear for a cancellation action.

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

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

The description goes well beyond the annotations (readOnly, idempotent, openWorld) by detailing the internal routing, the verdict taxonomy, and the meaning of special outcomes like could_not_verify (with verification_error) and unsupported. It also discloses the return format (verdict, evidence, citation, reasoning). This is high-value context that annotations do not provide.

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

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

The description is front-loaded with trigger phrases, then logically progresses to purpose, routing, outputs, and caveats. Every sentence contributes unique information—there is no fluff or redundancy. The length is justified by the tool's complexity, and the structure makes it easy to scan for key facts.

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 explains the return values (verdicts, actual value, citation, reasoning) and defines ambiguous outcomes. It also covers error semantics (could_not_verify vs unsupported) and the two execution paths. Given the complexity, this is a thoroughly complete description.

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

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

Although the schema already covers 100% of parameters, the description adds crucial semantics: tolerance_pct's role in overriding implied tolerance and its recommended setting for hallucination detection (1-2). The claim parameter is enriched with example inputs. This meaningfully enhances the agent's ability to use the parameters correctly.

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: natural-language claim verification against authoritative sources. It uses explicit trigger phrases like 'fact check' and 'verify the claim that…', and distinguishes itself by mapping to a specific verb+resource. It also explains the two-path routing (SEC EDGAR for financial claims vs grounded pipeline for all others), which differentiates it from sibling tools like ask_pipeworx or deep_research.

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

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

Explicit guidance is provided: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies when not to show results (could_not_verify) and explains the fallback behavior for non-financial claims. Though it doesn't name alternative tools, the scope and conditions are clearly delineated, making the appropriate usage unambiguous.

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