Duration

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that results include per-model scores, confidence, signals, and raw responses, and that the Anthropic integration requires a BYO key. This goes beyond annotations.

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

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

The description is concise (5 sentences), front-loads purpose, covers defaults, auth, returns, and use cases. 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?

Despite no output schema, the description details the return structure (per-model and combined view). All four parameters are explained, and use cases are given. Complete for a moderate-complexity tool.

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

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

Schema coverage is 100%, giving baseline 3. The description adds value by explaining default model behavior, the purpose of _apiKey (pass-through to Anthropic), and context as disambiguation aid.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores them 0-100 per model. It provides specific use cases (AI-marketing audits, pre-launch checks) but does not explicitly differentiate from siblings like scan_competitor_ai_presence.

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

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

The description explains when to use (brand audits, competitive monitoring) and how to configure models (default Workers AI free, Anthropic with API key). It lacks explicit when-not-to-use or alternatives, but the guidance is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context: the tool routes internally, fills arguments on the caller's behalf, and returns structured answers with citation URIs. It does not cover failure modes or rate limits, but that is a minor gap given the annotation coverage.

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

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

The description is long but tightly organized: directive first, then scope, mechanics, trigger phrases, examples, and sibling routing. Every paragraph earns its place for a broad router tool, and there is little 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 one-required-parameter router with no output schema, this is complete. It tells the agent when to use the tool, what it returns, how it behaves internally, and how it relates to grounded and deep-research alternatives. Nothing essential for selecting or invoking it 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?

The input schema already fully documents the question parameter and aliases, so the baseline is 3. The description adds value by explaining that the tool fills arguments automatically and by giving concrete natural-language example questions, which helps the agent understand how to phrase input.

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 names a specific action: routes the question to the right one of 5,767 tools and returns a structured answer with pipeworx:// citation URIs. It also differentiates from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', provides trigger phrases and concrete domains, and names alternatives: ask_pipeworx_grounded for extra verification, deep_research for broad/multi-part questions, and notes breaking-news is already handled.

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

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

Beyond the read-only, idempotent, and non-destructive annotations, the description discloses the beta status, the currently inactive candidate, and that results are compared against the stable router to decide merges. There is no contradiction with annotations.

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

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

The description is dense and front-loaded with the beta/identical relationship. It is slightly repetitive in saying both 'identical universal router' and 'currently matches ask_pipeworx exactly,' but each sentence serves the goal of clarifying an inherently confusing beta state.

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 an agent that knows ask_pipeworx, this is complete: it covers parameters, safety profile, current behavior, and the experimental purpose. It does not describe ask_pipeworx's core routing behavior or response shape, but the sibling reference and full schema coverage make that acceptable.

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

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

Schema coverage is 100%, with all parameters described as aliases for question, so the schema already carries the parameter meaning. The description only adds that arguments are identical to ask_pipeworx, which is helpful context but not new parameter-level semantics.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx: an identical universal router over the same tools and arguments, differing only in candidate routing improvements. It distinguishes this tool from the stable ask_pipeworx and other siblings without requiring schema inspection.

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

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

It gives an explicit selection criterion: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the stable router as the comparison baseline and explicitly clarifies that this is a full working router, not a fallback.

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

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

Discloses detailed behavior beyond annotations: it extracts answers only from tool results, returns evidence and confidence, and emits structured refusals with specific refusal_reason values. The read-only and idempotent annotations are consistent with the description, so there is 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 but every sentence adds value: mode, routing behavior, output contract, refusal cases, usage context, and cost tradeoff. It is front-loaded with the most decision-relevant phrase, making it highly scannable.

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

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

Given no output schema, the description fully specifies the success and failure return shapes, lists all refusal reasons, explains the extra LLM cost, and names the sibling to prefer for lighter queries. An agent has everything needed to invoke and interpret the result 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% since all six parameters are documented aliases for a single 'question' string. The description adds no parameter-specific meaning beyond the schema, but none is needed for such a simple interface, 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 names the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb and resource, and explicitly contrasts it with its sibling ask_pipeworx. This makes its distinct purpose immediately clear.

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

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

Explicitly instructs when to use it: whenever an answer will be quoted, cited, or acted on and fabrication is unacceptable. It also names ask_pipeworx as the cheaper alternative for casual lookups, providing clear routing 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral detail: fan-out patterns per category, response shapes, resolver contract with match confidence, parent event extractor, safety blocks for low confidence and closed markets, illiquid spread warnings, cancellation rules. No contradictions.

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

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

The description is lengthy but well-structured with section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and examples. Every sentence adds value; however, it could be slightly more concise without losing key details. Given the complexity, it is acceptable.

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

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

The description covers nearly every aspect: input types, resolution logic, fan-out examples, response fields, safety mechanisms, edge cases (closed markets, low confidence, cancellation rules), and fallback behavior for news. No output schema exists, but the description compensates thoroughly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds significant context: for 'market' it explains it can be slug/URL/text; for 'depth' it clarifies default and trade-offs; for 'include_raw' it describes when to use and impact on response size. This exceeds baseline.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It specifies the input types (slug, URL, question text) and output (evidence packet + comparison). The verb 'research' combined with specific resource 'Polymarket bet' differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

Explicit usage examples are given: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It also provides guidance on inspecting match confidence and provides a resolver contract, telling the agent when to trust results. This is comprehensive.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds context: for company type it pulls latest 10-K with off-calendar fiscal year handling, for drug type it pulls FAERS, FDA approvals, trial counts. Also mentions sorting by primary metric. 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?

Single paragraph front-loaded with trigger phrases, then explains behavior for both entity types. Every sentence adds value; no wasted words. Slightly longer but justified by complexity.

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

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

All parameters are explained, return type is described (paired data + citation URIs), and key behaviors for both entity types are covered. Without output schema, this is sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, but description adds meaning: explains that 'values' are tickers/CIKs for companies or drug names, and provides examples. This enriches the schema without repeating 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?

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with trigger phrases like 'compare X and Y' and explicit distinction from sequential lookups. It specifies the verb (compare), resource (entities), and scope (parallel call).

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear guidance. It describes when to use each type (company vs drug) but does not explicitly state when not to use the tool.

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

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

Beyond the read-only/idempotent/open-world annotations, the description discloses account requirements, paid-tier gating, groundedness with explicit gaps, contradiction reporting, semantic excerpting of large records, latency expectations, and that it is not open-web search. This gives the agent an unusually accurate behavioral model.

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

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

The description is dense but front-loaded with the most important facts: account requirement, core behavior, and when to use an alternative. It is longer than necessary and contains an awkward 'For example, notes:' transition, but almost every clause adds operational 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?

The definition is complete for a complex tool with no output schema: it explains the findings packet fields, gap/contradiction semantics, citation behavior, depth differences, latency, and exclusions. An agent has enough to call it and interpret results without relying on hidden conventions.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by clarifying that question is natural-language and should be broad/multi-part, and by noting that the thorough depth is paid and adds follow-up/contradiction behavior.

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, with explicit decomposition and parallel routing to other tools. It also distinguishes itself from open-web search and from the single-lookup sibling ask_pipeworx, so an agent can tell when this tool applies.

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

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

Usage conditions are explicit: use deep_research for broad/multi-part questions over structured data, use ask_pipeworx for single lookups, and use ask_pipeworx if not signed in. It also flags that thorough depth requires a paid plan, which is a concrete precondition.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description does not add behavioral details beyond what annotations give, but it does clarify that results are ready to call. Neutral value added, so baseline 3. 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?

Two sentences, but the first is a long list of domains. Still, it is well-organized and front-loaded with the core purpose. Could be slightly more concise, but effective.

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

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

Without an output schema, description explains that results include 'names, descriptions, and full input schemas (with curated examples)' and that each result is ready to call directly. Also mentions default and max limit. Covers all necessary contextual information for the agent.

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

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

Schema description coverage is 100% with detailed parameter descriptions. Description mentions query syntax and that results are ready to call, which adds minor context but does not significantly enhance parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool finds tools by describing data or task, listing many specific domains. It distinguishes itself from siblings by being the tool to call first for discovering available tools. The verb 'discover' and resource 'tools' is specific and accurate.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also provides a list of example uses, giving clear when-to-use 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?

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already conveying the safety profile, the description adds substantial behavioral detail: it fans out across multiple external sources, soft-fails on the USPTO patents API, reports sources_used/sources_failed, and explains that a private company returns resolved:false with a notes line. 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?

Long but information-dense: it front-loads user triggers and the core value proposition, then methodically covers sources, return fields, empty-data semantics, input variants, and the interchangeable type parameter. Every sentence carries operational value for an agent, with 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: CIK and company_name, up to 5 filings with pipeworx URIs, fundamentals fields, patents, contracts, FDA products, hiring, news, and LEI. It also explains edge cases like soft-fail behavior, empty sections being real 'no data', and private-company resolution, so an agent can invoke the tool and interpret results confidently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the ticker/CIK/company-name flexibility already in the schema and adds resolution behavior (resolved_from/resolved_to, private company handling), but those are output semantics more than parameter-level guidance. It doesn't materially change how an agent should fill `type` or `value` beyond what the schema already says.

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 concrete trigger phrases ('Tell me about X', 'research Acme') and defines an exact verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chaining single-pack lookups and lists the exact sources, making it clear this is the holistic company research tool rather than a narrow lookup.

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

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

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies when the tool still works but returns resolved:false (private companies), how to pass inputs, and that empty sections are expected 'no data' rather than errors. This is strong when-to-use and how-to-interpret 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?

Description adds context about why to delete (stale data, done task, sensitive data) beyond annotations. Does not elaborate on idempotency or error handling, but annotations already cover destructiveness and idempotency.

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

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

Two sentences, no fluff, front-loaded with the action. Efficient and clear.

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

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

For a simple single-parameter tool with annotations, the description covers purpose, usage guidance, and context. No output schema needed.

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

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

Schema already describes the only parameter 'key' as 'Memory key to delete'. Description adds 'by key' but no new semantic detail beyond the schema.

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

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

Clearly states verb 'Delete' and resource 'memory by key'. Distinguishes from siblings 'remember' and 'recall' by mentioning them.

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

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

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with remember and recall, providing clear context.

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

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

Annotations already indicate safe, idempotent, and non-destructive behavior. The description adds valuable context: keyless and offline operation, which supplements the annotations and aids agent decision-making.

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

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

The description is a single, well-structured sentence that conveys all essential information without redundancy. It is front-loaded and efficient.

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

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

Given the single parameter, high schema coverage, and clear annotations, the description fully covers what the tool does, its outputs, and operational context (keyless, offline). No additional information is needed.

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

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

Schema coverage is 100% with a description of 'Total seconds.' The description repeats 'number of seconds' but does not add additional constraints or format details. Baseline of 3 is appropriate.

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

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

The description clearly states the tool converts seconds to both ISO 8601 duration and human-readable form, with additional context of being keyless and offline. It effectively distinguishes itself from the sibling parse_duration by specifying the direction of conversion.

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 does not explicitly state when to use this tool versus alternatives like parse_duration. However, the purpose is clear enough that an agent can infer usage, but lacking direct guidance lowers the score.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds detail: fetches the page, extracts title/description/key links, emits markdown. This goes beyond annotations by explaining the process and output format.

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

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

The description is four sentences with no redundant words. It leads with the main purpose, followed by process, output, and use cases. Every sentence earns its place.

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

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

Given the simplicity (2 required params, no output schema), the description fully informs the agent about the tool's behavior, output, and typical use cases. No missing information.

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

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

Schema coverage is 100% with clear descriptions, so baseline is 3. The description adds defaults (max 25, up to 50) and the example format for url, providing additional context beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (fetch, extract, emit) and the output format. No sibling tool has overlapping purpose, so differentiation is inherent.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor visibility. It does not mention when to avoid using the tool, but the use cases are clear and context-specific.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields but no additional behavioral traits beyond annotations. Minimal added value.

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

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

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

Covers purpose and return fields. Lacks mention of the parameter's effect (include_inactive) and response behavior. Still sufficient for a simple list tool.

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

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

Schema coverage is 100% and the input schema already describes the parameter. Description does not add extra meaning or context beyond the schema.

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

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

The description clearly states "List the caller's active subscriptions" with specific verb and resource. It distinguishes from sibling tools like subscribe/unsubscribe by mentioning use cases for reviewing before adding or finding id to cancel.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' However, does not explicitly state when not to use or name alternatives, though implied by sibling context.

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

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

Annotations indicate read-only and idempotent behavior, which the description complements by noting 'keyless, offline' and detailing the approximation for months and years. This adds useful context beyond annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds value. No unnecessary information.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains what the tool returns (components and total seconds). It is sufficient given the tool's complexity.

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

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

With 100% schema description coverage, the schema already documents the parameter. The description provides examples but does not add significant additional meaning beyond the schema.

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

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

The description uses a specific verb 'Parse' and resource 'ISO 8601 duration string', clearly defining its function. It distinguishes itself from the sibling tool 'format_duration' which likely performs the reverse operation.

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

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

The description implies usage for parsing durations but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative suggestions are provided.

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

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

Beyond the minimal annotations, the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost implications ('Free; doesn't count against your tool-call quota'), and the claim-token workflow ('Filing without an account returns a `claim_token`; pass it back later...'). This goes well beyond what the annotations convey.

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

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

The description is long but packs each sentence with unique, actionable information: when to use, when NOT to use, how to phrase feedback, token mechanics, rate limits, and team processes. There is no fluff or repetition, and the most critical information (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?

Despite no output schema and minimal annotations, the description fully covers the tool's context: it explains the return value (claim_token), the workflow for checking resolution, real-world consequences (digests read daily, roadmap impact), and constraints (rate limits, free/quota). Everything an agent needs to use the tool correctly is present.

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 documents all four parameters thoroughly (100% coverage), so the baseline is 3. The description adds extra value by explaining the claim_token callback pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising on how to frame the message ('Describe the issue in terms of Pipeworx tools/packs'), which supplements the schema's descriptions.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly differentiates pipeworx_feedback from the many research and data tools listed as siblings, making its 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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog...') and gives a clear exclusion: file issues elsewhere if the tool came from a different MCP server. It even tells users how to check if a tool belongs to Pipeworx, providing thorough and practical 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, and idempotentHint. The description adds useful context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). No contradictions.

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

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

The description is concise: three sentences plus embedded bullet points. Each sentence adds value, and the most important information (what it returns) is front-loaded.

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

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

No output schema is provided, but the description states what is returned (top tools, top packs, total call volume). The single optional parameter is fully explained. Sufficient for effective use.

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

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

Schema coverage is 100% with a clear enum description. The description goes further by explaining the trade-off between shorter and longer windows ('surfaces what's hot' vs 'steady-state demand').

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

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

The description clearly states what the tool does: returns trending tools, packs, and call volume over a recent window. It distinguishes itself from siblings by focusing on aggregate trend data rather than specific queries.

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

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

The description lists three explicit use cases (discovering hot sources, confirming canonical choice, aligning with common needs). It does not state when not to use it, but the purpose is well-defined within the sibling context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds extensive behavioral context: mechanisms (Jaccard similarity, placeholder filtering, fill check), data sources (CLOB depth), and edge cases (partition placeholder >20% fraction returns null). No contradiction with annotations.

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

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

Description is long but well-structured: starts with purpose and modes, then dives into details with logical sections (semantic anchor, partition filter, fill check). Every sentence adds value; no wasted words given the 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?

Despite lacking output schema, the description fully explains the response structure: opportunities array with fields, partition_check object, fill check results. Input parameters are thoroughly covered. References sibling tool for custom sizing, completing the user journey.

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 basic descriptions. The tool description significantly enriches parameter meaning: explains event slug vs URL acceptance, topic as seed question, describes partition_check for event mode, and cross-event similarity anchor. Provides concrete examples like 'fed-decision-may-2026'.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Differentiates between trending_scan, event mode, and topic mode with specific examples. Distinct from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly specifies when to use each call mode: no args for trending scan, event for specific market, topic for cross-event scanning. Provides recommendations ('event recommended for specific market') and warns about conditions when not to trade (realizable_edge_pp ≤ 0).

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. The description adds extensive behavioral context: three model families, response segments (by_segment), edge calculation details (edge_pp_net, Kelly fractions, 24h move warning), tradeable-edge knobs, diagnostics for empty segments, and caching behavior. No contradictions.

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

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

The description is dense but well-structured with sections for models, response, knobs, and diagnostics. Front-loaded with core purpose. While verbose, each sentence adds value given tool complexity. Could be more concise, but effective.

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

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

Given no output schema, the description comprehensively covers return structure (by_segment segments, fed_candidates, diagnostics) and behavior (caching, knobs, edge calculation). All relevant aspects for an agent to invoke and interpret results are explained.

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 detailed descriptions. The description adds context on defaults, interaction between knobs (e.g., min_partition_leg_kelly vs min_kelly), and tradeable-edge filters. It explains nuances not fully covered in schema, like partition filtering logic. However, schema already does heavy lifting.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on intra-platform opportunities and daily 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 is built for agents discovering opportunities without paging hundreds of markets, implying usage for daily edge detection. It does not explicitly contrast with sibling tools, but the context signals and sibling list suggest differentiation. A more explicit when-to-use and when-not-to-use would improve clarity.

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

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

The description discloses extensive behavioral details: response structure with tracked, expired, and snapshot_dates arrays, interpretation of fields like trend and decay_pp_per_day, and limitations like snapshot gaps and TTL. Annotations already confirm read-only and idempotent, and the description adds significant context 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 detailed but well-organized: purpose, arguments, response, limitations. It is front-loaded with the core question. While dense, every sentence adds value, though it could be slightly tightened.

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 (time-series analysis, multiple response arrays, no output schema), the description covers all necessary information: response fields, interpretation, limitations, and data sources. It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100%. The description restates the parameters (days, window) with defaults and constraints, adding minimal context about their effect on snapshot range. Baseline 3 is appropriate as schema already documents them fully.

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

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

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

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

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

The description explains the use case: differentiating fresh vs. stale edges, implying when to use this tool (for historical analysis) vs. alternatives. It mentions limits like 60-day TTL but doesn't explicitly exclude other scenarios.

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

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

Annotations already set readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context: it 'walks the ladder', returns a 'verdict (clean|degraded|cannot_fill)', and specifically warns that 'partial basket fills convert an arb into an unhedged directional position (the dominant loss mode).' No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear section headers (SINGLE-MARKET, BASKET) and explicit usage guidance. Every sentence adds value, and the length is justified by the complexity of the tool's dual modes. Could be slightly more terse, but 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?

Given the complexity of the tool (two modes, no output schema), the description is comprehensive. It lists all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; for basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also explains edge cases like partial basket fills and thin legs, making the description fully adequate for an agent to understand the tool's 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%, so baseline is 3. The description adds significant meaning beyond the schema: it explains the dual mode logic (single-market vs basket), the auto default for basket side based on partition sum, and the different interpretation of size_usd for buys vs sells and basket settlement notional. This extra context justifies the above-baseline score.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by specifying usage before acting on their signals.

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 guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books; partial basket fills convert arb to directional position), effectively telling when to use and potential risks of not using.

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

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

Beyond the readOnly/idempotent annotations, the description extensively discloses runtime behavior: compatibility_codes can be non-empty even when matched_pairs>0, unknown-metric legs are never paired, temporal_alignment null means unknown not aligned, spreads are gross (fees not modeled), and pairing is always unverified. This gives an agent a realistic model of what results mean and what edge cases to expect.

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 organized for a complex tool: purpose, modes, response fields, safety codes, alignment semantics, fees, and counters are presented in a logical order. Nearly every sentence conveys needed caveats or behavior, so it is dense rather than padded. It loses a point because the length and opacity (e.g., 'skipped_cross_type / skipped_cross_subtype' details) could be trimmed for faster scanning.

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

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

With no output schema and no required parameters, the description carries the full burden of explaining return values and invocation semantics. It does so remarkably well: it covers raw probabilities, top_spreads_pp, compatibility_warning/codes, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. An agent has enough to call the tool and interpret results 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 each parameter is documented. The description adds meaningful semantics on top: the topic list is expanded into two modes, explicit tickers/slugs override the topic-mapped side, and both modes run the same matcher. This materially helps an agent choose between the topic shortcut and explicit pairing, though conflicts between simultaneous topic and explicit params are not spelled out.

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 precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This names the specific verb ('spread'), the resource (Kalshi vs Polymarket), and adds the cross-venue scope that distinguishes it from siblings like polymarket_arbitrage. The two-mode explanation further sharpens what the tool does.

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

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

The description gives clear context: use it when comparing the same question across Kalshi and Polymarket, and it warns when the spread is meaningful ('when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so'). It also cautions that pre-mapped topics are not necessarily tradeable. However, it never explicitly names alternative tools or says 'use X instead when...', so it misses explicit 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, idempotentHint, and destructiveHint. The description adds context about listing all keys when omitted and scoping to identifier, which goes beyond annotations. It does not contradict and provides behavioral insight about the tool's operation.

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 just two sentences, front-loading the core purpose. Every sentence adds value: first sentence states functionality, second explains usage with examples and pairings. No wasted words.

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

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

Given the tool is simple (1 optional param, no output schema), the description covers purpose, usage, scoping, and relationships with sibling tools. It provides sufficient context for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% and documents the optional key parameter. The description adds meaning by explaining the effect of omitting key (list all keys) and provides context about what types of values can be retrieved (ticker, address, research notes). This enhances understanding beyond the schema's description.

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

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

The description clearly states the tool retrieves a saved value or lists keys, using specific verb 'Retrieve' and specifying the resource (values saved via remember). It distinguishes itself from siblings 'remember' and 'forget' by naming them and describing the complementary actions.

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

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

The description explicitly tells when to use (to look up stored context without re-deriving), gives examples (ticker, address, research notes), and mentions scoping and pairing with remember/forget. This provides clear guidance on appropriate use cases 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?

The description discloses behavioral details beyond annotations: returned event structure (source, citation_uri, raw payload) and the side effect of mark_read:true (flags events as read). However, the description contradicts the readOnlyHint annotation by describing a state change.

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 4 sentences, front-loaded with the main purpose, and covers features, parameter guidance, and an alternative. It is efficient but could be slightly tighter (e.g., combining the last two 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?

Given 5 parameters and no output schema, the description covers purpose, parameter usage with examples, and return structure. It also provides a scenario (mark_read effect) and a REST alternative. No major gaps; limit parameter behavior and since inclusivity are implied.

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

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

All 5 parameters are covered in the schema, and the description adds meaningful context: example for type ('sec_8k'), ISO timestamp for since, and explanation that mark_read:true causes subsequent calls to show only newer events. This goes beyond the schema's short descriptions.

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

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

The description clearly states it pulls fired events from a subscription feed, specifying the resource (subscription feed alerts) and the action (pull/return). It distinguishes itself from sibling tools like subscribe or list_subscriptions by focusing on retrieving already-fired events.

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

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

The description mentions that polls work fine and provides an alternative REST endpoint for scripts/dashboards, giving context on when to use the tool versus the API. It also gives filter examples (type, since) but does not explicitly state when not to use it or compare to other sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fans out to three sources, GDELT preferred, GNews fallback, USPTO soft-fail, returns grouped changes with citations. No additional details on rate limits or pagination, but still strong.

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

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

Well-structured with front-loaded examples and clear sections. Slightly verbose but every sentence adds value; could be trimmed slightly without losing meaning.

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 and 3 parameters (100% schema coverage), the description is very complete: it explains return structure (changes[] grouped by source, total_changes, citation URIs), data source specifics, and parameter formats. No gaps.

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

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

Schema coverage is 100%, but the description adds practical guidance: 'since' accepts ISO date or relative shorthand ('7d', '30d', '3m', '1y') with recommendation '30d' or '1m', 'value' can be ticker or CIK, 'type' only supports company. This significantly enriches 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 a change feed for a company (SEC filings, news, patents) in a given time window, with specific verb 'retrieve recent changes' and distinguishes from sibling tool entity_profile.

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

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

The description provides numerous example queries, explains when to use ('what's new', 'latest on Y'), explicitly directs to entity_profile for static profiles, and details data source fallback behavior (GDELT→GNews, USPTO soft-fail).

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

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

Adds behavioral info beyond annotations: key-value scoping, persistence differences for authenticated vs anonymous users (24-hour retention). Annotations already indicate idempotency.

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?

All sentences provide essential information: purpose, when to use, how it works, scoping, persistence, and companion tools. No redundancy.

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

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

Given no output schema, the description fully covers the tool's function, usage context, behavioral nuances, and relationship to sibling tools.

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

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

Schema coverage is 100%, baseline 3. Description adds value with example key patterns (subject_property, target_ticker) that clarify typical usage.

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

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

Description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource, distinguishes from siblings like recall and forget.

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

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

Provides explicit 'Use when' guidance and mentions paired tools, but does not explicitly state when not to use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds significant behavioral context: it cascades through multiple endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns ambiguity via `figi_candidates` instead of guessing, and explicitly exposes unresolvable identifiers under `unresolved`. These details go beyond annotations and are critical for agent expectations.

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 densely packed with necessary details. It is front-loaded with illustrative examples and the 'Use FIRST' directive, then systematically covers supported types, edge cases, and degradation behavior. While not concise, every section earns its place given the tool's complexity. One minor deduction for length and some redundancy in the company-type narrative.

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 semantics, and it does: it mentions `figi_candidates`, `unresolved`, source labelling, and the graceful degradation behavior. It covers all input types, edge cases (non-US issuers, bonds without tickers), and clearly states what the tool will not do. An agent would be fully equipped to call 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%, but the description adds substantial meaning beyond the schema's terse parameter descriptions. For `type`, it explains the two enum values and their behavior. For `value`, it gives concrete input formats (ticker, CIK, ISIN, name) and warns about the exact phrasing for bonds. This is exactly the kind of guidance an agent needs to construct correct calls.

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 clear verb-resource pair: resolve a user-spoken NAME to canonical identifiers. It is explicit about what it does and what it does not (asserting nothing on ambiguous bond matches). It also names the usage context (inputs for other tools) and distinguishes itself from siblings by enumerating supported entities and the specific sources involved.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', which is a clear when-to-use directive. It also provides detailed usage examples for the `value` parameter, including a caution against including security-class words for bonds. While it does not name alternative tools, the 'FIRST' directive and the coverage of edge cases make the usage guidance 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?

Discloses that it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, signal density. Also mentions the first entity is treated as the 'subject'. All this adds value beyond the annotations which declare readOnlyHint, openWorldHint, etc. 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?

Three sentences, front-loaded with the main action, then process details, then usage example. No wasted words.

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

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

Describes inputs, process, and outputs (ranked list with score, confidence, signal density). Lacks mention of potential limitations (e.g., rate limits, API key requirements for models) but is sufficient for a tool with good annotations and schema.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds minimal extra meaning beyond the schema (e.g., first entity as subject is already in 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 uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and resources ('AI visibility across multiple entities', 'ai_visibility_check'), and distinguishes from siblings like 'ai_visibility_check' which is implied as a single-entity probe.

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

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

Provides a concrete use case ('competitive AI-marketing audits') with an example question. Does not explicitly state when not to use, but context makes it clear this is for multi-entity comparison vs. single check.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia latency (5-30s), and sources_failed reporting.

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?

Starts with a concise summary of the tool's purpose, then elaborates with important details. Slightly long but each sentence adds value.

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

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

Despite lacking an output schema, the description enumerates return fields, edge cases (partial failures, latency), and behavior, making it complete for a composite tool.

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

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

Schema covers 100% of parameters with clear descriptions. Description adds context: scoped packages accepted and version defaults to latest, which is not 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?

Clearly states it's a composite check for npm packages covering safety, size, and licensing. Distinguishes from sibling tools like deps.dev:version by noting ecosystem limitations.

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

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

Provides explicit when-to-use examples ('is X safe/popular/small') and ecosystem scope ('NPM ecosystem only in v1'). Clarifies alternatives for other ecosystems.

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

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

Adds concrete behavioral details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation. No contradiction with readOnlyHint, openWorldHint etc.

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

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

Concise paragraph, front-loaded with purpose, then essential details. No wordiness. Every sentence adds value.

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

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

Despite no output schema, description explains return value clearly. Covers embedding model, windowing, size limit, and usage context. Complete for a semantic 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?

Schema coverage is 100%, but description adds value by explaining output format (character offsets, similarity scores) and giving example queries. Slight redundancy with schema for text 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?

Clearly states verb 'search' and resource 'inside a fetched record'. Specifically mentions semantic search and distinguishes from sibling tools by pairing with 'ask_pipeworx_grounded'.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits like saving context and returning only relevant passages. Suggests complementary tool for grounding.

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

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

Annotations indicate the tool is not read-only, is idempotent, and not destructive. The description adds behavioral context: requires OAuth, returns a new id, delivery constraints (SMS cap, webhook auto-disable after 10 failures), and always-on feed. No contradiction with annotations. The description complements the annotations effectively.

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, starting with the core purpose, then requirements, supported types with examples, and delivery channels. It is front-loaded and each sentence adds value. Slightly lengthy due to detail, but appropriate for the complexity.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers purpose, return value (id), requirements, all param types, and delivery options. Missing error handling or idempotency details, but overall sufficient for agent selection and invocation.

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

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

Schema coverage is 100%, but the description greatly enhances parameter understanding. It explains each type enum value with examples (e.g., sec_8k with items, polymarket_edge with topic), details the params object per type, and describes delivery options with constraints (e.g., SMS must be verified, webhook HMAC signing). This adds significant meaning beyond the schema.

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

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

The description clearly states it creates a proactive monitoring subscription and returns the subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by specifying the action of creation. Supported types and delivery channels are listed, 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 for when to use the tool (proactive monitoring) and specifies requirements (Pipeworx OAuth account, not anonymous/BYO). It includes examples for each subscription type, aiding in selection. However, it does not explicitly state when not to use this tool vs alternatives, though sibling tools imply other actions.

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

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

Annotations already provide readOnly, openWorld, idempotent, nondestructive hints. Description adds that it returns example questions from a live catalog with tool+argument shapes, which is useful behavioral context beyond annotations.

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

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

Description is somewhat long but well-structured, front-loaded with typical user query patterns. Could be slightly more concise, but every sentence adds value.

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

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

No output schema, but description explains return type (category-bucketed examples with tool+arguments). Given the tool's low complexity (discovery), this is sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with description for topic. Description adds value by explaining that omitting topic returns full cross-category spread, which goes beyond schema meaning.

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

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

Description clearly states the tool is an onboarding entry point that returns category-bucketed example questions with exact tool calls. It uses specific verbs like 'returns' and 'draws from', and distinguishes from sibling tools like ask_pipeworx and 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?

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to use topic vs full spread. Also mentions learning how to call meta-tools, providing clear context.

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

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

The description reveals key behaviors beyond annotations: deactivation vs. deletion, and that historical events remain available via recent_alerts. Annotations already indicate non-destructive (destructiveHint: false) and idempotent, which the description complements.

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 conveying all necessary information without redundancy. Front-loaded with the action and resource, efficient and clear.

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

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

For a simple tool with one parameter, no output schema, and informative annotations, the description is sufficient. It covers purpose, ownership, and side effects. Minor omission: does not specify error handling for invalid or non-owned ids, but overall adequate.

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 only parameter 'id' is fully described in the schema (uuid returned by subscribe). The description adds no further semantics beyond implying the id identifies the subscription. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the action ('cancel a subscription') and the resource ('by id'). It distinguishes from sibling tools like 'subscribe' (create) and 'list_subscriptions' by specifying cancellation with ownership enforcement.

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 ownership enforcement ('you can only cancel your own subscriptions'), guiding when the tool is applicable. It does not explicitly mention when not to use it or alternatives, but the context with sibling tools makes it 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?

The description goes well beyond the read-only/idempotent annotations by explaining the SEC EDGAR fast path, the grounded pipeline fallback, return verdict types, and the critical distinction between could_not_verify (pipeline failure, not evidence) and unsupported (no source). This is rich behavioral context that helps callers interpret results safely.

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, with a front-loaded trigger phrase list, clear behavioral segmentation, and a dedicated caller warning section. Every sentence earns its place, and the structure flows logically from purpose to usage to return values to caveats.

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

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

With no output schema, the description fully explains what the tool returns: verdict types, actual value with citation, and reasoning. It also covers failure modes and error handling (verification_error with stage/detail), making it contextually complete for a claim-verification tool.

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

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

Schema already covers both parameters at 100%, but the description adds significant meaning: tolerance_pct has its range (0.5–50), default behavior ('implied by wording, capped at 5'), and a concrete use case (set 1–2 for hallucination detection). The claim parameter also gets realistic examples, making both parameters more actionable.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources' with explicit trigger phrases like 'fact check' and examples. It distinguishes itself from sibling tools by noting it replaces 4–6 sequential calls and narrowing scope to factual claims.

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

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

Provides explicit use context: 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates sub-paths for company-financial vs other claims. However, it lacks explicit alternatives or 'when not to use' guidance, so it earns a strong 4 rather than 5.

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