lorem

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details: the default model is free Workers AI Llama-3.3-70b, Anthropic probing requires a BYO key with direct payment, and the return structure is disclosed. Minor gap: no mention of rate limits or result pagination, but the description exceeds the baseline.

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

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

The description is three sentences long, front-loaded with the core action and outcome, then moves to model options and costs, then return format, then use cases. Every sentence adds essential information with no fluff or repetition of schema field names. It is model-efficient and easy to parse.

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

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

Even without an output schema, the description discloses the return format precisely ('per-model {score, confidence, signals, raw_response} + a combined view') and covers default behavior, optional payment, and canonical use cases. With only one required parameter and clear optional flags, this is a complete operational picture for an AI agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the default worker-ai model, clarifying that _apiKey is passed directly to api.anthropic.com, and that context helps disambiguate common names. These details help the agent correctly populate parameters without needing extra inference.

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 action: 'Probe one or more LLMs for what they know...' and a measurable outcome ('score visibility (0-100) per model'). It clearly distinguishes the tool from siblings like scan_competitor_ai_presence by focusing on LLM knowledge probing and scoring. The mention of a default model and optional Anthropic probe makes the purpose even more concrete.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and pragmatic guidance on when to pass _apiKey ('to also probe Anthropic'). It doesn't explicitly warn against using this tool vs alternatives, but the use cases and model options give clear context for when it's appropriate.

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

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

Annotations already establish readOnly, openWorld, and idempotent behavior. The description adds useful behavioral context beyond that: it routes to one of 5,767 tools, fills arguments automatically, and returns answers with stable pipeworx:// citation URIs. Some operational details like latency or result size are not covered, but the safety-relevant behavior is well disclosed.

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

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

The description is front-loaded with the key 'prefer over web search' instruction, includes concrete examples, and then provides escalation paths for alternatives. It is longer than minimal but every section earns its place; slight redundancy around web-search comparison keeps it from a 5.

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

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

For a single-required-parameter tool with no output schema, the description is complete: it explains scope, examples, routing behavior, citation URIs, and when to choose alternative tools. An agent has everything needed to decide whether to call ask_pipeworx and what kind of input to provide.

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%: the schema fully documents the required 'question' parameter and its aliases. The description reinforces that the input is a natural-language factual question with examples, but it does not add meaningful parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states that ask_pipeworx routes factual questions to the right specialized tool and returns a structured, cited answer. It explicitly distinguishes itself from web search and names sibling alternatives (ask_pipeworx_grounded, deep_research), so an agent can identify its role precisely.

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 strong when-to-use guidance: 'PREFER OVER WEB SEARCH' for current or historical factual data, lists trigger phrases, provides concrete examples, and even says to use it when web search could also answer. It also names alternatives for hallucination-resistant answers and broad multi-part research, making the selection logic explicit.

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 disclose the safe read-only/idempotent/open-world profile. The description adds valuable behavioral context: it is a live experimental edge, may currently behave identically to ask_pipeworx, and no candidate routing is active right now. However, it doesn't detail response format or pagination, and the 'betrays nothing' aspect is already mostly covered by 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 every sentence earns its place: it establishes identity, current state, usage, and the experimental purpose. It is front-loaded with the most important information (beta/identical router) and ends with the fallback clarification.

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

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

The tool is fully specified by the schema, annotations, and description: the agent knows its arguments, its safe behavior, when to use it, and how it differs from the stable sibling. Without an output schema, the description still covers the essential context, and the beta-vs-stable distinction fully addresses the only real ambiguity.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including aliases. The description only says 'same arguments' without adding new semantic detail beyond the schema. That meets the baseline for high schema coverage but doesn't exceed it.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, an identical universal router with the same tool set, arguments, and response shape. It explicitly distinguishes it from the stable ask_pipeworx sibling and explains why an agent might choose it.

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 to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It also clarifies that there is no fallback—this is a full working router—so the agent knows it can be used standalone. This gives clear when-to-use guidance relative to the sibling tool.

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

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

Goes well beyond the annotations by disclosing the exact success return shape, all refusal reasons, the 'only what the tool result contains' extraction constraint, and the additional LLM call cost. These behavioral details add significant context that annotations alone cannot convey.

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

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

Dense but well-organized: the core behavior is front-loaded, followed by return/refusal contract and usage guidance. A small amount of routing detail (5,767 tools, 1506 sources) is illustrative but not strictly necessary; still, every major sentence earns its place.

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

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

For a one-question-parameter tool with rich annotations and no output schema, the description fully covers invocation, return contract, refusal semantics, and when to choose this over the sibling. Nothing essential for correct agent use is missing.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for a single natural-language question. The description adds no parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate; no compensation is needed.

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

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

The description clearly defines this as a hallucination-resistant, grounded answer mode that routes through the same machinery as ask_pipeworx but extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing evidence-grounded extraction and explicit refusals.

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: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete domains listed. It also names the alternative and gives the trade-off: prefer ask_pipeworx for casual lookups because this costs one extra LLM call.

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

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

Annotations already mark readOnly=true, idempotent=true, and destructiveHint=false, so the safety profile is covered. The description goes far beyond this: it discloses parallel fan-out, low-confidence short-circuit status, closed-market handling, wide-spread tradeability warnings, resolution-rule cancellation risks, and news-fallback behavior. No contradiction with annotations; these are additive behavioral details.

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 it is organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. Each section provides substantive guidance for safe and effective use. While not minimal, the density of critical behavioral information justifies the length for this complex tool.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly documents the evidence packet, market-vs-model comparison, resolver contract (match confidence/score/alternatives/suggestions), parent-event extraction, news fallback fields, and blocking safety statuses. This is comprehensive coverage of the tool's behavior and 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 covers 100% of parameters (market, depth, include_raw) with clear descriptions. The description adds examples of market input formats and fan-out behavior, but does not introduce meaning for depth or include_raw beyond the schema. This matches the baseline for high schema coverage where structured data carries the load.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_edges and polymarket_arbitrage by emphasizing evidence aggregation and market-vs-model comparison. The input types (slug, URL, question text) and classifier list further nail the purpose.

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

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

It provides explicit usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear when-to-use guidance. However, it does not explicitly name alternatives or state when not to use this tool, only implying that other tools may fit other use cases.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. 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 dense and well-structured, leading with example queries, then core functionality, type-specific details, sorting behavior, and output. Some redundancy in the query examples could be trimmed, but each sentence contributes useful information.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete: it states return format (paired data + citation URIs), sorting order, data specifics, and handles nuanced cases like off-calendar fiscal years. All key aspects are covered.

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

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

The schema covers both parameters at 100%, but the description enriches the 'type' parameter by explaining that 'company' pulls 10-K financials and 'drug' pulls FAERS/FDA/trial data. This goes beyond the schema's minimal enum description, though the values array is adequately specified in the schema.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, using specific verbs like 'compare' and 'rank.' It distinguishes itself from sequential single-pack lookups, making its purpose unambiguous and distinct 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?

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives concrete query examples and elaborates on what each 'type' retrieves, giving clear when-to-use and how-to-use instructions.

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; the description adds substantial context on top: explicit gaps[] rather than invented answers, resolvable citation_uri values, semantic excerpting, contradictions[] behavior in standard/thorough, latency expectations, and account gating.

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

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

The description is dense and front-loaded with the most important usage gate, but it is a long unbroken paragraph with repeated details (paid plan mentioned twice, citation/URI described twice) and several long parenthetical clauses. Structured bullets would significantly improve scannability.

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

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

Even though there is no output schema, the description fully characterizes the output findings packet, gaps, contradictions, citation behavior, latency, auth requirements, and when to prefer alternatives. An agent has enough context to invoke this 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 the baseline is 3, but the description adds meaning beyond the schema: it explains depth tiers in terms of hops, gap recovery, contradiction scanning, and paid requirements, and clarifies that the question parameter supports broad/multi-part natural-language queries.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources in one call. It clearly distinguishes itself from open-web search and from ask_pipeworx, and it includes concrete example question types.

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

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

The description explicitly tells the agent when to use this tool versus alternatives: use ask_pipeworx for single lookups, prefer it for breaking/current news, and use deep_research for broad/multi-part questions over structured data. It also gives account and paid-tier prerequisites and says to fall back to ask_pipeworx when not signed in.

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 and idempotentHint, so the description adds value by revealing return behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... no second schema lookup needed.' This goes beyond what annotations provide. It doesn't cover rate limits or auth, but those are less relevant given the read-only/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?

The description is longer than average due to the domain list and return detail, but every sentence contributes. It is front-loaded with the core purpose and ends with a direct usage directive. No filler or repetition.

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

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

For a discovery tool, the description covers its input (natural language query), its output (top-N tools with schemas), and its recommended usage order. There is no output schema, but the description fully explains the return format. Combined with rich schema annotations, no gaps remain.

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

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

The schema has 100% coverage with explicit descriptions for all parameters, including aliases and examples. The description repeats some query examples but adds no meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with 'Find tools by describing the data or task,' specifying a clear verb and resource. It distinguishes this meta-tool from sibling data-specific tools by emphasizing discovery and returning ready-to-call tool schemas.

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 you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context and implies alternatives (using specific tools directly).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral context beyond that: parallel fan-out across sources, soft-fail behavior for sunset APIs, the meaning of sources_used/sources_failed, empty-section semantics, and resolved:false for private companies. 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 section carries information: examples, preference guidance, source fan-out, return fields with caveats, and input semantics. It is dense rather than wasteful, though a bit of line-break structure could improve scannability.

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 there is no output schema, the description carries the full burden of explaining return values and does so thoroughly: it lists cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also handles edge cases like private companies, empty data, and API sunset behavior.

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

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

Schema coverage is 100%, but the description still adds meaningful value by explaining that type 'company' and 'ticker' are interchangeable, that value can be a ticker, zero-padded CIK, or company name, and that names resolve via SEC EDGAR's company-name match. This goes well beyond the schema's field descriptions.

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

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

The description states a specific verb and resource: it builds a 'full cross-source profile of a US public company' in one parallel call. It lists concrete user phrasings ('Tell me about X', 'research Acme') and explicitly differentiates itself from chaining single-pack SEC/XBRL/news lookups.

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

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

The description is explicit about when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers input variations (ticker, CIK, name) and the edge case of private companies, making the selection criteria and invocation behavior 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 destructiveHint and idempotentHint. The description adds context by specifying exactly what gets destroyed: 'a previously stored memory by key,' and mentions use cases like clearing sensitive data. This goes beyond the annotations to clarify the scope of the destructive action.

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 effectively convey the action, usage context, and relationship to sibling tools. The description is front-loaded with the primary purpose and contains no unnecessary words or redundancy.

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

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

For a simple one-parameter tool with no output schema, the description covers the functionality, when to use it, and how it fits with related tools. Annotations supply the destructive and idempotent behavior, so no additional details are needed. The tool is fully contextualized.

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

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

Schema coverage is 100%, with the key parameter already described as 'Memory key to delete.' The description simply reiterates 'by key' without adding new meaning or usage details beyond the schema. Baseline 3 is appropriate since the schema fully documents the parameter.

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: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), and distinguishes itself from sibling tools like remember and recall by specifying deletion as opposed to storage or retrieval.

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

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

The description explicitly provides when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names sibling tools ('Pair with remember and recall') to clarify the workflow 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context: it fetches the page, extracts content, and emits a text blob in standard llms.txt format. This goes beyond annotations by describing the operational process and output shape, though it does not mention error handling or rate limits.

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: the first states the core function, the second explains the process, and the third lists concrete use cases. Every sentence contributes value with no redundancy or fluff. It is front-loaded with the key verb and resource.

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

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

Given the tool's simplicity (2 parameters, simple output), the description is complete. It explains the input (URL), the process, the output format (single text blob ready to drop at site-root/llms.txt), and common use cases. No output schema exists, but the description explicitly covers what the return value looks like.

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

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

Schema description coverage is 100%, and both parameters (url and max_links) have clear descriptions. The tool description does not add significant parameter-level detail beyond what the schema provides, so the 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 a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly explains what the tool does (fetches page, extracts title/description/key links, emits standard llms.txt markdown) and distinguishes it from siblings by focusing on producing an output file rather than analyzing or scanning.

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

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

The description provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not name alternative tools or say when not to use it, but the context is clear enough for an agent to decide when this tool is appropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context that the output is plain text without formatting, which is not captured by annotations. This goes beyond the baseline safety profile.

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

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

The description is a single sentence that front-loads the verb, resource, and use case, and adds the return format. Every word earns its place; there is no filler or redundancy.

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

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

The tool is simple with only two parameters and an output schema. The description covers the core purpose, use case, and return format, while the schema handles parameter details and examples. No significant information gaps remain.

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

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

Schema description coverage is 100% for both parameters ('count' and 'length'), including types, ranges, and enum values. The description adds no new parameter-level information, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Generate') and resource ('placeholder text paragraphs'), with an explicit purpose ('for mockups and layout testing') and return type ('plain text without formatting'). This clearly distinguishes it from sibling tools like generate_with_options or generate_llms_txt.

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

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

It provides clear context for when to use the tool ('for mockups and layout testing'), but does not explicitly mention alternatives or when not to use it. No exclusions are given, but the purpose is specific enough to guide selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that the output is HTML and that the text is placeholder content, providing useful context beyond the annotations without contradicting them.

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

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

A single sentence that is front-loaded with the main purpose and immediately lists the configurable options. No wasted words, every phrase earns its place.

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

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

The tool is simple (generation, no side effects) and benefits from strong annotations, a complete parameter schema, and an output schema. The description fully covers the tool's purpose and key options, making it complete for an agent to invoke correctly.

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

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

Input schema has 100% coverage with detailed descriptions for all parameters, including examples. The description only reiterates the element options (headers, code blocks, lists) without adding new semantics beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('Generate formatted placeholder text') and enumerates the distinct features (headers, code blocks, unordered/ordered lists). This distinguishes it from the sibling generate_paragraphs tool by highlighting the configurable elements.

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 usage context (when you need formatted placeholder text with specific elements) and tells the user to specify which elements to include. It does not explicitly mention alternatives or exclusions, but the sibling generate_paragraphs is implicitly the simpler choice.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: it operates only on the caller's subscriptions, returns specific fields, and defaults to active subscriptions (implied by the include_inactive parameter). This goes beyond the annotations without contradicting them.

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

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

Two concise sentences: the first states the action and return fields, the second provides actionable usage guidance. Every sentence earns its place with no redundancy.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete. It specifies the operation, scope, return fields, and practical use cases, leaving no critical gaps.

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

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

Schema description coverage is 100% for the single parameter (include_inactive), so the schema fully documents it. The description adds no additional parameter-level detail, which aligns with the baseline of 3 for high coverage.

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

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

The description uses a specific verb ('List') and clearly identifies the resource: 'the caller's active subscriptions'. It also lists return fields (id, type, params, created_at, last_fired_at, fire_count), distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This implies when to use the tool but does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses asynchronous behavior (team reads digests daily), token-based follow-up semantics (claim_token), rate limiting (5 per identifier per day), and cost (free). No contradictions with annotations exist.

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

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

The description is dense but every sentence serves a purpose. The first sentence states the core function, then it systematically covers when to use, when not to use, how to describe issues, token behavior, and rate limits. No filler or repetition—all details are operationally relevant.

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 4 parameters, nested objects, no output schema, and nuanced usage rules, the description is complete. It explains return values (claim_token), follow-up invocation, exclusions, rate limits, and message format. An agent has everything needed to invoke it correctly and reason about outcomes.

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

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

Schema descriptions already cover 100% of parameters, so the baseline is 3. The description adds value by explaining the claim_token round-trip flow ('pass it back later... to read whether it was fixed'), specifying message length (1-2 sentences, 2000 chars max), and reinforcing that context is optional. This meaningful usage guidance exceeds the schema.

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

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

The description opens with a specific, action-oriented statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team) and the action (providing feedback). This makes it unmistakable from sibling tools like ask_pipeworx or discover_tools.

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

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

The description explicitly enumerates when to use the tool: for bugs (wrong/stale data), feature requests, data gaps, and praise. It also provides a clear exclusion—'if the tool came from a different MCP server... file it with that server instead'—and even helps disambiguate by noting that Pipeworx tool names are those this connection lists. This is exemplary usage guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses the data source ('derived from CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h'). This adds non-obvious context about the tool's behavior.

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

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

The description is well-structured: it opens with the core purpose, then lists use cases, then adds background notes on aggregation and caching. Every sentence adds value, and it is appropriately sized for the tool's moderate complexity.

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

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

Even though there is no output schema, the description explicitly mentions the return contents ('top tools, top packs, and total call volume'), plus additional context like window semantics, caching, and privacy. Combined with strong annotations, this is a complete picture for an agent.

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

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

The single parameter 'window' is fully described in the schema, including the default and trade-off between windows. The tool description repeats the enum values but adds no new semantics beyond the schema, so the baseline 3 applies.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now' and specifies outputs ('top tools, top packs, and total call volume'). It distinguishes itself from siblings like ask_pipeworx or discover_tools by focusing on aggregated trending 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?

Provides explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choice, checking alignment with agent needs. However, it does not explicitly mention when not to use it or name alternative tools, so it's slightly below the full 5.

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

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

Even though annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds critical behavioral nuance: the fill check warns that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' It also details thresholds (Jaccard ≥0.30, >3pp deviations) and placeholder filters beyond what annotations provide.

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

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

The description is long but every sentence carries operational value. It is well-structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the primary purpose and mode selection before diving into details. No redundant or filler 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?

With no output schema, the description must explain return values, and it does: it specifies that response includes 'opportunities[] (gap_pp, suggested_trade, reasoning...)' and in event mode 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge cases like null arb signals and skipped_low_similarity, making the tool 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?

The schema only gives brief parameter descriptions (e.g., 'A topic or seed question'), but the description enriches both parameters: it provides concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), states that full Polymarket URLs are accepted, and explains behavior like 'walks child markets' for event mode and 'searches related events' for topic mode.

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

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

The description clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket) and the method, and it is distinct 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?

The description provides explicit usage patterns: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also directs users to 'polymarket_fill_risk' for custom sizing, acting as a clear alternative.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by disclosing internal model calculations, caching behavior ('Cached 1h at the KV level'), response diagnostics, and limitations (e.g., unreliable Fed signal). It also reveals that opportunities include a 24h-move warning when edge may be priced in, which is valuable 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 extremely verbose, packing in precise alphas (tennis 1.02, soccer 1.10, MMA 1.15), gate thresholds, and model formulas. While it is organized with numbered families and sections, it is not concise and could overwhelm an agent; much of the detail would be better placed in documentation or output schema.

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

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

Despite lacking an output schema, the description fully specifies the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, etc.). It even explains why diagnostics exist, making the tool's behavior fully comprehensible.

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 covers all 9 parameters (100% coverage), the description adds relational meaning by explaining how knobs interact, e.g., 'min_partition_leg_kelly filters partitions by best per-leg Kelly' and that partition arbs ignore min_kelly at parent level. It also clarifies slippage subtraction, enhancing the schema's individual field descriptions.

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

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

The description opens with a clear verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes the tool from siblings by naming three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with concrete examples, making its function unmistakable.

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

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

It clearly states the intended use case ('Built for "what should I bet on today"') and explains how knobs like min_liquidity/max_spread_pp refine results. It does not explicitly name alternatives or exclusion criteria relative to siblings, but it provides strong contextual guidance such as why Fed bets are excluded from ranking.

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

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

The annotations already indicate a safe, read-only, idempotent operation. The description adds substantial behavioral context: source from daily snapshots, TTL limits, signed edge_pp_net values, snapshot gaps due to cache-miss behavior, and decay computed on daily closes. This exceeds the baseline and provides the agent with meaningful operational knowledge.

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

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

The description is long but information-dense; every sentence either clarifies the tool's purpose, explains response fields, or notes limitations. It is well-structured with clear sections for args, response, and limits, and avoids redundancy.

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

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

With no output schema, the description compensates by exhaustively detailing the response structure, including tracked[], expired[], snapshot_dates[], and their meanings. It also covers data freshness, snapshot gaps, and computational basis, making the tool's behavior and output fully predictable.

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

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

The input schema already describes both parameters (days and window) with their defaults and clamps, so coverage is 100%. The description's prose repeats the defaults and adds 'snapshot family' context but provides little additional 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 clearly states the tool provides edge persistence and decay telemetry, answering whether an edge is new or shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series history rather than current edge values.

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

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

The description provides clear context on when to use the tool (to understand edge age/decay and differentiate fresh vs stale opportunities). However, it does not explicitly cite alternatives or state when not to use it, such as deferring to polymarket_edges for current edges only.

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?

While annotations already declare readOnlyHint=true, the description goes far beyond: it explains the tool walks the order-book ladder, returns detailed fill risk metrics, and warns about partial basket fills converting an arb into an unhedged directional position. This adds substantial behavioral context beyond safety 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?

Despite its length, the description is tightly structured: first sentence states purpose, then REQUIRES, then SINGLE-MARKET and BASKET modes with their respective inputs/outputs, ending with explicit usage guidance. Every sentence adds necessary information; no word is wasted.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does thoroughly: it enumerates all outputs for both modes, including verdict values, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers parameter constraints and risks, making the tool's behavior fully predictable.

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, so the baseline is 3, but the description significantly enriches every parameter: it explains the difference between market and event modes, interprets size_usd differently for buys vs sells and for basket settlement notional, and clarifies the default side logic. This transforms the schema from bare enums into actionable guidance.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and explicitly names the sibling tools it complements, leaving no ambiguity about its purpose.

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 this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of not using it, providing clear context versus alternatives.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds extensive behavioral detail: compatibility fields can be non-empty even when pairs are returned, unknown legs are never paired, temporal_alignment null means not computable, and the fee caveat is disclosed ('spread_pp is gross, not a net tradeable edge'). 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 it front-loads the core purpose and mode distinction, then layers caveats that genuinely affect invocation and interpretation. Some phrasing is repetitive ('in EITHER mode', repeated warnings about reading compatibility fields), but the complexity of the tool justifies most of the length. It is structured rather than bloated.

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

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

With no output schema, the description carries full responsibility for explaining the response shape, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning, compatibility_codes[], flags[], skipped_cross_type/subtype, temporal_alignment, and fees_note. It also covers edge cases like unknown legs, unaligned months, and unverified pairings. Nothing essential is missing.

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

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

Schema coverage is 100%, so parameters already have descriptions. The tool description goes further by explaining the two-mode interaction, listing all pre-mapped topics, defining override behavior ('Overrides the topic-mapped Kalshi side'), and clarifying that both modes run identical matching logic. This adds real 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 opens with a crisp definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the operands (Kalshi, Polymarket), the computation (spread), and the matching condition (same resolving question). It also distinguishes the two modes of invocation, making the tool's scope 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 clearly states when to use each mode: pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug pairings. It also gives practical caution: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly name alternative sibling tools or say when not to use this tool, but the context is strong.

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 this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: scoping to the caller's identifier and the dual behavior (retrieve single key vs. list all keys). It doesn't mention edge-case behavior like key-not-found, but that's minor given the strong annotation coverage.

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

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

Four sentences, each earning its place: the first gives the core action, the second the use case and benefit, the third the scoping constraint, the fourth the sibling tool relationships. No filler, and the main purpose 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?

For a simple tool with one optional parameter and no output schema, the description covers the core function, the list-all-keys variant, scoping, and how it interacts with remember/forget. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% (the 'key' parameter is fully described as 'Memory key to retrieve (omit to list all keys)'). The description reinforces this and adds concrete examples of what keys might be (user's target ticker, address, research notes), offering more semantic guidance than the bare schema.

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

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

The description opens with a clear, specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It immediately distinguishes from related siblings (remember, forget) and gives concrete examples of what the tool retrieves.

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 this tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the companion tools for the full lifecycle: 'Pair with remember to save, forget to delete.' This provides clear context and differentiates from alternatives.

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

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

The description explicitly states that setting mark_read:true flags returned events as read, which modifies the feed state. This directly contradicts the annotation readOnlyHint: true, which claims the tool is read-only. Per rubric, any such contradiction mandates a score of 1 and an annotation contradiction flag.

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 cohesive paragraph with no fluff. It leads with the action, then return value, filtering, mark_read semantics, and then the HTTP alternative. Every sentence earns its place and the structure is logically ordered and 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?

For a 5-parameter tool with no output schema, the description covers the return payload, filtering, mark_read state changes, polling suitability, and a mirror endpoint. It relies on the schema for limit/unread_only but gives enough context for correct usage. The annotation contradiction is a notable inconsistency, but the description itself is fairly complete, so a 4 is appropriate.

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

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

The schema covers all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description adds valuable context by giving an example for 'type' (sec_8k), clarifying 'since' as an ISO timestamp, and detailing how 'mark_read' affects subsequent calls. This added meaning justifies a score of 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 'Pull fired events from your subscription feed', a specific verb and resource, clearly identifying the tool as an alert/event retriever. It further specifies the return contents (source, citation_uri, raw payload) and filter capabilities, distinguishing it from siblings like list_subscriptions and recent_changes.

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

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

The description provides clear usage context: it mentions polling works, gives an HTTP alternative (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, and explains filtering by type/since and mark_read for read tracking. However, it does not explicitly state when to avoid this tool in favor of siblings, so it falls short of a 5.

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

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

Even though annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavioral detail: it fans out to three sources, explains fallback logic, notes the PatentsView API sunset and soft-fail, and discloses the return shape with grouped changes and citation URIs. This goes well 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 dense but well-organized: front-loaded with query intents, then source details, parameter guidance, and return shape. Every sentence adds useful information without redundancy, and it remains scannable despite its length.

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

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

This is a complex tool with multiple upstream data sources, fallbacks, and a soft-failing component. The description explains the output structure (changes[] by source, total_changes, pipeworx:// URIs), covers all three parameters' semantics, and gives enough context for an agent to decide when to use it. No output schema exists, so this narrative completeness is essential and achieved.

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 100% of parameters with descriptions, but the description adds meaningful semantics: explains `since` relative shorthand ('7d', '30d', '3m', '1y'), provides concrete examples for `value` (ticker vs CIK), and reiterates that `type` only supports company. This adds 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 clearly states it is a change feed for a company over a recent window, with concrete example queries ('What's new with X'). It explicitly distinguishes from sibling entity_profile ('Use entity_profile instead when you want the static profile'), making the tool's specific scope unmistakable.

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

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

Provides explicit usage context: natural-language intents, one parallel call, source fallback behavior (GDELT preferred, GNews on rate-limit/5xx), and USPTO soft-fail. It also names the alternative tool entity_profile and even recommends a typical value for `since` ('30d' or '1m'), which is actionable 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 cover readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: key-value storage scoped by identifier, persistence duration (24h for anonymous), and cross-session/within-conversation scope. It doesn't mention overwrite behavior, but the idempotent hint partially covers that. This exceeds the baseline while not being exhaustive.

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

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

The description is four sentences, front-loaded with purpose, then usage, then technical details, then companion tools. Every sentence adds distinct value with no redundancy or filler. It is efficiently structured for an AI agent to parse quickly.

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

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

For a simple two-parameter tool with no output schema and helpful annotations, the description covers purpose, usage, persistence, and companions. It lacks explicit details about return values or edge cases (e.g., overwriting an existing key), but those are minor given the tool's simplicity and the absence of an output schema. Overall, it is nearly 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 description coverage is 100%, with both 'key' and 'value' clearly described in the schema. The description adds minimal parameter-level detail beyond examples in the usage section, which reinforces but does not significantly extend the schema. Baseline 3 is appropriate.

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

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

The description opens with a clear, specific verb and resource: "Save data the agent will need to reuse later." It explicitly distinguishes from siblings by naming recall (retrieve) and forget (delete), and provides concrete examples of what to store, leaving no ambiguity about the tool's function.

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

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

The description states exactly when to use the tool: "Use when you discover something worth carrying forward" and lists example use cases. It also explains the pairing with recall and forget, and clarifies persistence conditions for authenticated vs anonymous sessions, giving the agent a full decision framework.

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, and the description adds substantial behavioral context: ambiguous matches return figi_candidates without asserting a result, unresolved identifiers appear under `unresolved` rather than being omitted, enrichment degrades gracefully if GLEIF/OpenFIGI are unavailable, and each call cascades through multiple endpoints. 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?

Purpose and usage guidance are front-loaded, followed by supported types and caveats. It is dense and long, with many parentheticals, but nearly every clause carries unique, decision-relevant information, so the length is justified by tool 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?

For a 2-param tool with no output schema, the description covers input interpretation, ambiguity behavior, unresolved output shape, identifier source labeling, fallback degradation, and which entity types are supported. An agent has enough information to invoke the tool correctly and interpret its 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% but the descriptions are generic. The tool description greatly extends meaning: it explains ISIN-to-LEI resolution, the strict 'issuer exactly as printed' caveat for bond names, the difference between brand and generic drug names, and why trailing security-class words break the FIGI lookup.

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?

States a specific verb and resource: resolve a user-spoken NAME to canonical/official identifiers other tools require. It enumerates example queries and supported types, and explicitly frames the tool as 'Use FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools like entity_profile.

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

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

Provides clear usage context: 'Use FIRST whenever you have a name but need an ID,' with concrete example phrasings and supported types. It notes the tool replaces 2-3 manual lookups, but it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds behavioral context beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses the output shape (ranked list with score, confidence, signal density). This enriches the agent's understanding of the tool's internal process and outputs.

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, front-loaded with the primary action, followed by mechanism, use case, and output. Every sentence earns its place: the first states purpose, the second explains process, the third provides a concrete application and return format. No fluff or repetition.

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

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

Given the tool's moderate complexity (multi-entity probing, ranking), the description covers the main facets: what it does, how it works (via ai_visibility_check), when to use, and what it returns. It doesn't detail error handling or edge cases (e.g., entity limits), but with annotations clarifying safety and idempotency, the description is largely complete. The only minor gap is not explicitly noting the 2-8 entity limit (present in schema).

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

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

Schema coverage is 100% and each parameter has a description. The description adds no new parameter semantics beyond what the schema provides; it only mirrors the 'first entry as subject' rule (already in schema) and mentions 'N competitors' which is implicit in the entities array. This meets the baseline for high schema coverage without adding extra value.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling ai_visibility_check by focusing on multi-entity comparison and ranking. The example query 'does Claude know about us as well as our competitors?' anchors the purpose in a concrete scenario.

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 states when to use it: 'Useful for competitive AI-marketing audits' and gives a concrete example. It also implies the alternative (ai_visibility_check for single entities) by saying it probes each entity with that tool, though it doesn't explicitly say 'use this instead of ai_visibility_check when comparing multiple entities.' Clear context but missing explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds substantial context beyond that: partial failures degrade gracefully, first measurement can take 5-30s, sources_failed lists timeouts, and the return summary block fields are enumerated. This gives the agent a detailed execution model absent from 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?

Though dense, every sentence earns its place: purpose, use cases, return fields, and limitations. It is front-loaded with the core purpose and the structure is logical (purpose → usage → output → caveats). No filler or redundant repetition of schema details.

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 composite tool with no output schema, the description is remarkably complete. It describes the return block, per-advisory details, links, alternative versions, failure modes, timing, and ecosystem exclusions. There is no extraneous dependency on a 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?

The schema already covers both parameters 100% (package name and version default). The description does not add additional parameter-specific meaning—it focuses on behavior and output. Per the rubric, when schema coverage is high, baseline 3 applies.

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

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

The description clearly states a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It distinguishes itself from siblings by detailing the fan-out across deps.dev and bundlephobia. The use-cases ('is X safe / popular / small' or 'what does adding lodash cost me') make the purpose unmistakable.

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

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

Explicitly provides when-to-use guidance: 'Use whenever an agent asks...'. It also gives a clear exclusion: 'NPM ecosystem only in v1' and points to an alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Even covers partial failure behavior.

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

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

Annotations already declare read-only and idempotent behavior. The description goes beyond by disclosing the truncation cap ('longer inputs are truncated and flagged'), the internal mechanism (BGE-base-en embeddings + cosine over 500-char overlapping windows), and that each passage includes a character offset for verification. 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 four sentences, each earning its place: core action, use case, sibling pairing, and technical caveat. It is front-loaded with the most important information and contains no fluff or repetition of schema details.

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 discloses the return format (top-N passages with character offsets and similarity scores). It covers purpose, usage, limits, and mechanism, making the tool fully understandable for an agent without needing extra context. It is complete for a read-only search tool.

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

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

The input schema has 100% coverage with detailed descriptions for all three parameters (text max length, limit range/default, query examples). The description adds no new per-parameter meaning; it only reiterates the 200K character cap. Thus baseline 3 is appropriate, as the schema does the heavy lifting.

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

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

The description opens with 'Semantic search INSIDE a fetched record', which combines a specific verb ('search') with a clear resource ('a fetched record') and distinguishes it from siblings by the 'INSIDE' emphasis. It also specifies the return type (top-N passages with offsets and scores), making the purpose unmistakable.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides a direct alternative/complement in 'Pairs with ask_pipeworx_grounded', indicating when to use the sibling instead of the whole document. This is clear, actionable guidance.

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

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

The description adds significant behavioral context beyond annotations: OAuth account requirement, per-channel delivery details, SMS 10/day cap, webhook auto-disabled after 10 failures, and return of a webhook secret once. These details inform the agent about side effects and constraints that annotations (readOnlyHint=false, destructiveHint=false) don't fully cover. 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 densely packed but well-structured with lists of types and delivery channels. It front-loads the core purpose and return value, then details each type and delivery option. Every sentence provides useful information, though it is somewhat long; still, it earns a high score for avoiding 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 the tool's complexity (3 params, nested objects, no output schema), the description covers essential aspects: prerequisites, return value, subscription types with examples, and delivery channels. It lacks error behavior or how to manage subscriptions, but those are likely handled by sibling tools. The description is sufficiently complete for an agent to invoke the tool correctly.

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

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

Although schema description coverage is 100% and heavily repeats the same examples, the description adds interpretive value like 'items:["5.02"] = officer change' and emphasizes the proactive nature. It also clarifies the 'delivery' object's constraints (e.g., phone verification, 10/day cap) which are already in the schema but reinforced here. The extra semantics warrant a score above 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's function: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return ('Returns the new subscription id'). It distinguishes the tool from siblings like 'recent_alerts' and 'list_subscriptions' by focusing on creation of subscriptions rather than retrieval or management.

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

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

The description provides clear context: it's for proactive monitoring, requires a Pipeworx OAuth account, and notes an alternative pull method (feed via 'recent_alerts or GET registry.pipeworx.io/alerts.json'). It also mentions prerequisites like phone verification for SMS. However, it doesn't explicitly contrast with alternatives like 'unsubscribe' or 'list_subscriptions', so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is known. The description adds value by explaining the output composition (category-bucketed examples with tool+argument shapes) and that it draws from the live catalog, which is not in 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 densely packed but structured: it opens with example queries, states the purpose, then details output, usage, and timing. Each sentence serves a distinct function, though the opening list could be trimmed slightly; overall it is appropriately sized for an onboarding tool.

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

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

With no output schema, the description adequately explains the return structure and purpose. It also provides context about the live catalog and meta-tools, making it complete for a simple one-parameter tool with rich annotations.

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

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

The schema already covers 100% of the parameters, fully documenting the optional `topic` parameter with allowed values and omission behavior. The description reinforces this with examples but does not introduce new semantic information, meriting the baseline score 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 identifies the tool as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by instructing to 'Use this FIRST' and by naming meta-tools to learn, making its unique purpose explicit.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides instructions on calling with no arguments or passing a `topic` to focus, which serves as clear usage guidance.

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

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

The description discloses important behavioral traits beyond annotations: ownership enforcement, deactivation rather than deletion, and that historical events remain available via recent_alerts. This adds substantive context about side effects and data persistence, complementing the annotations without contradiction.

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

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

The description is two sentences, front-loaded with the core action, and every sentence earns its place. It is concise and well-structured, covering the action, ownership rule, and deactivation behavior without waste.

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

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

For a simple mutation tool with one parameter, no output schema, and informative annotations, the description is complete. It explains the operation, the ownership restriction, the non-destructive nature, and the impact on historical data, leaving no critical gaps.

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

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

Schema description coverage is 100% (id is fully described as a uuid returned by subscribe). The description does not add further parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource, distinguishing it from siblings like subscribe and list_subscriptions. It includes the parameter (id) and key constraints, 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 the tool (cancel a subscription) and includes a constraint (ownership enforced) and a pointer to recent_alerts for historical data. However, it does not explicitly name alternatives like list_subscriptions or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare read-only and idempotent. The description adds crucial behavior: the structured vs grounded routing, meaning of special verdicts (could_not_verify vs unsupported), that could_not_verify must not be shown as evidence, and that unsupported means no source coverage. This goes beyond annotations and prevents misuse in agent reasoning.

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 dense and purpose-driven, covering triggers, routing, return value, edge cases, and efficiency. It is front-loaded with trigger phrases and structured logically. Every sentence contributes necessary information for correct use of a complex tool, so no waste.

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

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

For a tool with no output schema, the description fully covers return values (verdicts, evidence, reasoning), the two execution paths, and the important distinction between could_not_verify and unsupported. It also explains the integration benefit over multi-step pipelines, making it complete for its complexity.

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

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

Schema coverage is 100% with well-written parameter descriptions: claim has examples, tolerance_pct explains override and default. The description text doesn't add much beyond the schema for parameters, but it does contextualize tolerance_pct with the cap and hallucination-detection use case. This is baseline for full schema coverage.

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

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

The description clearly states the tool is for natural-language claim verification with explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…'), and distinguishes it from sibling tools by scoping to factual claim checking. It also details the two execution paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else), making the purpose unmistakable.

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

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

It says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a direct usage context. It also notes that the tool replaces 4–6 sequential calls, implying it should be used as a single-call alternative. It doesn't explicitly name alternatives like ask_pipeworx_grounded, but the context is clear and specific enough.

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