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 readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false, so the baseline safety profile is clear. The description adds valuable context about routing logic, citation URIs (pipeworx://), and that it works 'on every tier' in 'one fast call,' but does not detail behavior on empty results, timeout, or data freshness. 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 but front-loaded with the core value proposition. It packs significant guidance into a few sentences, but the long parenthetical list of alternatives and the 'what's the world saying' clause could be condensed slightly. Overall efficient 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 rich annotations and complete schema, the description covers routing behavior, alternatives, examples, and citation format adequately. There is no output schema, so the description doesn't need to describe return values beyond mentioning 'structured answer with stable pipeworx:// citation URIs'. A solid completion for a single-parameter tool with high schema coverage.

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 adds meaning beyond the schema by explaining the parameter's purpose ('Your question or request in natural language') and listing aliases (q, prompt, text, input), but the schema itself already provides these aliases in descriptions. The description's examples add practical context.

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 ('routes', 'fills arguments', 'returns') and clearly identifies the resource as a meta-router across 5,564 verified sources. It distinguishes itself from sibling tools by naming alternatives like ask_pipeworx_grounded and deep_research, and provides concrete examples of supported 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 explicitly states 'PREFER OVER WEB SEARCH' and provides clear when-to-use guidance for factual questions with structured data. It also specifies when to use alternatives: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. Examples like 'current US unemployment rate' illustrate appropriate 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 declare readOnlyHint, idempotentHint, and destructHint=false, establishing safety. The description adds valuable context about the experimental nature, current state (no active candidate), and that it is a full working router, not a fallback. 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 a single, well-structured paragraph that front-loads the key identity ('Beta version of ask_pipeworx'), then efficiently explains behavior, current state, usage, and nature. 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?

The description is complete for this beta tool: it explains the relationship to the stable version, the experimental routing mechanism, current equivalence, usage instructions, and that it is a full router. The response shape is mentioned as identical to ask_pipeworx, which is sufficient given no output schema.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question'. The description adds no parameter-specific meaning beyond stating 'same arguments' and referring to the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with candidate routing improvements. It distinguishes itself from the stable sibling by highlighting its experimental nature and current equivalence when no candidate is active.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared to the stable router to decide merges. This provides clear context for when to choose this tool over its stable counterpart.

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 fully discloses the extraction process, return format (answer, evidence, confidence, source, fetched_at, refusal_reason), and refusal reasons (not_in_source, no_tool_match, etc.). Annotations already indicate readOnly, openWorld, idempotent, non-destructive; the description adds rich behavioral context beyond these.

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 paragraphs, front-loaded with the key concept, and every sentence adds significant value. No wasted words; it efficiently conveys purpose, behavior, usage, and return format.

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 (6 alias parameters, no output schema), the description fully compensates by detailing the return structure, refusal reasons, and usage context. The agent has all necessary information to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all 6 parameters being aliases for 'question' and each described in the schema. The description does not add additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by specifying the grounded extraction behavior, and the title and description together differentiate it from other siblings.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to use ('prefer ask_pipeworx for casual lookups'), including specific examples (financial verdicts, legal claims, medical lookups, public statements) and cost trade-off (one extra LLM call).

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

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

Annotations 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond those: it explains the tool decomposes questions into facets, routes them in parallel to 5,564 tools, returns a findings packet with verbatim evidence plus gaps[] and contradictions[] for certain depths, semantically excerpts large records, provides citation URIs, and gives expected timing ranges (15-60s, up to 90s). No contradiction with annotations.

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

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

The description is long (three paragraphs) but each sentence contributes essential information—account requirements, core behavior, alternatives, output shape, timing, edge cases. It is front-loaded with the most critical usage warning (account needed, alternative tool). However, a minor reduction could improve scanability without losing meaning; for example, combining the three depth bullet explanations into a more compact form.

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

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

Despite having only two parameters and no output schema, the description fully compensates by detailing the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation URIs, gaps, contradictions, hop field), explaining error/edge behavior (empty gaps for off-catalog topics), and noting timing. No required aspect is left unaddressed; an agent can confidently decide to invoke this tool and interpret its results.

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

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

Both parameters are already described in the schema (100% coverage). The description adds significant value by explaining the depth enum: 'quick=3 (single hop)', 'standard=3 (default; adds gap-recovery hop + contradictions scan)', 'thorough=6 (paid; full iterative hop + contradictions scan)'. For the question parameter, it clarifies that 'broad/multi-part is fine — decomposition is the point.' This enriches the schema definitions.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in a single call, distinguishes itself from open-web search, and provides specific examples of suitable questions (e.g., 'compare X and Y's regulatory + financial exposure'). It also names a direct sibling (ask_pipeworx) for single lookups, making differentiation explicit.

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

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

Explicitly states that an account is required, offers a free tier via GitHub, notes that 'thorough' depth needs a paid plan, and directs unsigned-in users to ask_pipeworx. It further advises using ask_pipeworx for single lookups or breaking news topics, and describes when deep_research underperforms (topics not in the structured catalog, returning empty gaps). This provides clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

Annotations already 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: fans out across multiple sources, patents sunsetting, soft-fail behavior, and fallback mechanisms. 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 a single dense paragraph but front-loaded with examples. Every sentence adds value, though breaking into sections could improve readability.

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

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

Despite no output schema, the description thoroughly explains what is returned (cik, filings, fundamentals, patents, news, LEI) and notes limitations. Covers all aspects needed 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% and descriptions are clear. The description adds meaning beyond schema by explaining that value can be ticker or CIK and that names are not supported, and that type currently only supports company.

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 provides a clear and specific verb-resource pair ('full cross-source profile of a US public company') and distinguishes from sibling tools like resolve_entity. It includes example queries that indicate the tool's purpose.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view' and advises using resolve_entity when only a name is available. Clear when to use and when not to.

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?

Annotations are readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: two operation modes, response structure (leg prices, spreads, safety fields), conditions for compatibility_warning (shape mismatch, semantic mismatch), and temporal alignment check. 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 well-structured with clear sections indicated by keywords (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, but the density may challenge quick scanning. Slightly verbose for a description.

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

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

No output schema, so description fully covers return values (leg prices, spreads, safety fields with conditions). Also explains edge cases (compatibility_warning triggers, temporal alignment). Complete for a complex read-only tool with optional parameters.

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

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

Schema coverage is 100% (all three parameters described in schema). Description adds significant value: enumerates the 10 topic shortcuts, explains they auto-fetch matching events, and provides example tickers for explicit mode. Exceeds minimal schema info.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same question. Describes two distinct modes (topic shortcuts and explicit pairing). Distinguishes from sibling polymarket tools by focusing on cross-venue spread.

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 guidance on when to use (to compare same-outcome prices across venues) and warns about incompatibility via compatibility_warning. Explains that most pre-mapped topics are not yet tradeable. Does not explicitly compare to alternatives but indirectly guides away from unmatched 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 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 mark it read-only, idempotent, and non-destructive. The description adds valuable behavioral details: identifiers are labelled with their source, unresolved ones appear under `unresolved`, and LEI/FIGI enrichment degrades gracefully if external sources are unavailable. These go beyond annotation hints.

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

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

The description is long but well-organized with examples, a clear purpose statement, and a structured breakdown of supported types. Every sentence adds information, though some agents might find the length slightly overwhelming. Still, it 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 tool's complexity (cascading lookups, multiple identifier types, fallback behavior), the description covers all necessary context: what it does, when to use it, what inputs are accepted, how errors/unresolved IDs are handled, and how it relates to manual workflows. No output schema exists, so the description sufficiently explains the return behavior without over-specifying.

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?

Though schema coverage is 100%, the description significantly enriches parameter meaning: explains that `type` accepts 'company' or 'drug' with full context, and `value` can be a ticker, CIK, ISIN, or name, including an example of ISIN-to-LEI resolution. This adds clarity far beyond the raw 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 resolves a user-spoken NAME to canonical/official identifiers, with concrete example queries. It distinguishes from siblings by specifying it's the first-stop for name-to-ID lookups, contrasted with tools like entity_profile or compare_entities.

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?

Gives explicit guidance with 'Use FIRST whenever you have a name but need an ID.' It also explains supported types and input formats. However, it doesn't explicitly state when not to use it or mention alternative tools beyond the implicit 'replaces 2-3 manual lookups'.

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

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

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.