Malwarebazaar

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds key behavioral details: default model, BYO key for Anthropic, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 efficiently structured sentences: first sentence states purpose and scoring, second sentence covers model options and return format. Front-loaded with key info, no wasted words.

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

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

Despite no output schema, the description explicitly states the return format and covers all parameters. For a 4-parameter tool with 100% schema coverage, this is fully 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining default model, _apiKey requirement only for Anthropic, and clarifies that 'context' helps disambiguate. This raises it to 4.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It names the default model and optional Anthropic probe, distinguishing it from sibling tools 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 specifies use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. While it doesn't explicitly exclude alternatives, the context is clear enough for an agent to decide when to use it.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it routes to many internal tools, auto-fills arguments, emits stable citation URIs, works on every tier, and is a single fast call. No contradiction, and the added detail justifies a score above baseline.

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

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

The description is long but well-structured and front-loaded with the most critical directive ('PREFER OVER WEB SEARCH'), followed by domain list, mechanics, usage triggers, examples, and escalation paths. Each section earns its place, though a slight redundancy in the news mention keeps it from being perfectly concise.

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

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

For a complex routing tool with no output schema, the description is remarkably complete: it covers supported domains, usage triggers, examples, alternatives (grounded, deep_research), news behavior, and output characteristics (structured answer with citation URIs). It gives the agent all the context needed to decide when to use this 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 description provides example questions but doesn't add meaning beyond what the schema already documents for the six aliases. Baseline of 3 is appropriate since the schema carries the parameter semantics; the examples illustrate usage but don't deepen field-level understanding.

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 ('routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with citation URIs') and clearly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research. It states exactly what the tool does and how it differs from alternatives.

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

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

Explicit when-to-use guidance is given: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also provides when-not-to-use by directing to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part queries, plus news routing behavior.

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

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

Given the annotations already declare it read-only, open-world, idempotent, and non-destructive, the description adds valuable context: it's an experimental edge that may have live routing improvements enabled, currently matches the stable router exactly, and is a fully functional router. This goes beyond the annotations without contradicting them.

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

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

The description is four sentences and information-dense, with the main purpose front-loaded ('Beta version of ask_pipeworx'). Every sentence contributes useful context about current state, usage, and experimental nature, though it could be slightly more concise.

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

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

Given the tool's experimental complexity and lack of an output schema, the description thoroughly covers the current state (no active candidate), the relationship to the stable router, and the full-working nature. It mentions the same response shape, indirectly addressing output expectations, but doesn't detail specific return values.

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

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

The input schema covers all 6 parameters (question and aliases) with 100% description coverage, so the baseline is 3. The description merely says 'same arguments' without elaborating on the meaning of the question parameter or its aliases, providing no additional value beyond the schema.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. This gives a specific verb+resource and distinguishes it from the stable sibling ask_pipeworx by its experimental, testable nature.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router and that it falls back to nothing, meaning it's a full working router. However, it does not explicitly state when NOT to use it, leaving room for ambiguity.

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

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

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral context: it only uses the tool result, never invented facts, returns evidence quotes, and provides a structured refusal with five specific reasons. This goes far beyond the annotations.

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

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

While longer than a two-sentence description, every sentence earns its place: purpose, routing mechanism, return shape, refusal reasons, use cases, and cost trade-off. The structure is logical and front-loaded with the most important label.

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

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

Despite lacking an output schema, the description fully documents return values and refusal modes. It also covers the decision context, cost implications, and alternative tools, making it complete for a complex tool with high-stakes usage.

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

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

Schema coverage is 100% and the schema already explains the 'question' parameter and its aliases. The description doesn't add new parameter-level detail beyond noting that the tool 'fills arguments' internally, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific, distinctive purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from the sibling 'ask_pipeworx' by emphasizing grounded extraction and explicit refusal behavior, and it specifies the exact return contract.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' with domain examples, and explicitly names the alternative: 'prefer ask_pipeworx for casual lookups.' It also notes the cost trade-off, which helps the agent decide.

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 (readOnlyHint=true, etc.) are supplemented with extensive behavioral details: resolution mechanisms, fan-out to multiple datasources, handling of closed markets, wide spreads, cancellation rules, and safety short-circuits. No contradiction with annotations; description adds significant 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?

Description is thorough but verbose, containing many sections (RESOLVER CONTRACT, PARENT_EVENT, etc.). Every sentence is informative, but the length may overwhelm an AI agent. Could be more concise without losing critical details.

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

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

Given no output schema and moderate complexity, description covers input types, all behavioral edge cases, result structure (market, analysis, evidence), and special cases (low confidence, closed markets, cancellation rules). Very complete.

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

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

All three parameters have schema descriptions (100% coverage). Description adds further meaning by explaining the 'depth' enum values and the 'include_raw' boolean's effect on payload size. Enhances understanding beyond schema.

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

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

Description clearly states the purpose: research a Polymarket bet by pulling Pipeworx data in one call. Provides specific input examples (slug, URL, question text) and output summary (evidence packet + market-vs-model comparison). Distinguishes from sibling tools like polymarket_arbitrage by focusing on data research.

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

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

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides guidance on interpreting results (RESOLVER CONTRACT, PARENT_EVENT) and handling low-confidence matches. However, does not explicitly exclude sibling tools for specific tasks like arbitrage.

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 rich behavioral details: data sources, handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction.

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

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

The description is relatively long but front-loaded with example invocations and key instructions. Every sentence adds meaningful information, though it could be slightly more concise without losing value.

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

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

Given the tool's complexity (two entity types, no output schema), the description comprehensively explains input requirements, data sources, sorting, and output format (paired data + citation URIs). It leaves no essential 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%, baseline 3. Description adds value by interpreting the 'type' parameter as selecting data source and specifying that 'values' accepts tickers/CIKs for companies and drug names, with min/max constraints clearly stated.

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

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

The description clearly specifies the tool's function: side-by-side comparison of 2-5 companies or drugs, with distinct data sources (SEC EDGAR for companies, FAERS for drugs). It distinguishes itself from sibling tools like entity_profile and sequential single-pack lookups.

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

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

The description explicitly states to prefer this tool over sequential lookups for comparisons, provides example queries, and explains sorting behavior. It lacks explicit when-not-to-use guidance but is clear on 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?

Goes far beyond annotations (readOnly, openWorld, idempotent) by disclosing account requirements, parallel routing to 5,529 tools, the never-invented gaps[] behavior, contradictions[] scanning, citation_uri fetchability, semantic excerpting, and latency expectations. This rich behavioral detail is exactly what agents need to invoke the tool correctly.

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 (~300 words) but densely packed with essential information and front-loaded with account requirements and core function. Some redundancy exists around citation details and the citation_uri explanation, and it reads as a wall of text rather than scannable structure. Still, every sentence contributes value for a complex tool.

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

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

No output schema exists, so the description carries full responsibility for explaining return values. It comprehensively covers the findings packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field), performance expectations, and failure modes (empty gaps for non-catalog topics). This is complete for a research tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining depth tiers' behavioral effects (standard re-angles gaps, thorough chases leads) and confirming the question parameter accepts broad/multi-part natural language. This is a moderate but real value-add over 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's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with decomposition and parallel routing. It distinguishes itself from ask_pipeworx by explicitly positioning deep_research for broad/multi-part structured-data questions, making the purpose unmistakable.

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

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

Explicitly provides when-to-use guidance: 'Best for broad/multi-part questions over structured data', and gives concrete alternatives: 'For a single lookup use ask_pipeworx' and for breaking/current news prefer ask_pipeworx. It even specifies account-tier fallback, making the decision tree crystal 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds that results include full schemas with examples and are ready to call directly. No contradiction with annotations.

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

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

The description is a single paragraph but dense with information. Every sentence adds value, but it could be slightly more concise. Well-structured: purpose, domain list, return behavior, usage hint.

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 explains what is returned (top-N tools with names, descriptions, schemas) and how to use the tool. Covers aliases and limit parameter. Complete for a search/discovery 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%, baseline 3. The description adds value by noting aliases for query and providing concrete examples of good queries, which aids understanding beyond schema descriptions.

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

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

The description explicitly states the tool finds tools by describing data or task, and lists numerous example domains like SEC filings, FDA drugs, etc. It also distinguishes itself from sibling tools by advising to call this first when many tools are available.

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

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

Clearly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives explicit context and hints about 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?

The description discloses multiple behavioral traits beyond annotations: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF and returns specific fields. It notes that patents soft-fail after sunset, news uses GDELT→GNews fallback, and names are not supported. Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description aligns with these (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 paragraph but effectively front-loaded with example queries and the key purpose. It covers all necessary details without extra fluff. However, it could be slightly more structured for easier scanning (e.g., bullets for return fields).

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

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

Given the tool's moderate complexity (multiple sources, conditional behavior for patents, no output schema), the description provides complete information: it lists all data sources, the fields returned, and notes the patent sunset. It also explains the input constraints (ticker or CIK). This enables correct selection and use without additional context.

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

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

Schema coverage is 100% (both parameters are described in the schema). The description adds meaningful detail: 'value' must be a ticker or zero-padded CIK, not a name; 'type' currently only supports 'company'. This expands on the schema's enum and description.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' It lists example queries and specifies the verb (profile/overview) and resource (US public company). It distinguishes from sibling tools by explicitly stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed.

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

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

The description gives explicit guidance: use when user asks for a holistic view of a company. It provides a list of example intents ('tell me about X', 'research Acme', etc.). It also states when NOT to use it: if only a name is available, use resolve_entity first. It contrasts with chaining single-pack lookups, making the usage context 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 set destructiveHint=true; description adds context about clearing sensitive data and pairing with other tools, which is valuable beyond the annotation.

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

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

Two sentences, front-loaded main action, no waste. Every sentence adds value.

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

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

For a simple 1-param tool with annotations and full schema coverage, the description sufficiently covers purpose, usage, and context without needing return value details.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add details beyond the schema's 'Memory key to delete', but no additional explanation needed due to full coverage.

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

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

Clearly states 'Delete a previously stored memory by key' with specific verb and resource, and distinguishes from siblings by mentioning pairing with remember and recall.

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

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

Explicitly describes when to use: stale context, task done, or clearing sensitive data. Does not explicitly say when not to use but provides clear positive contexts.

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 fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. Annotations already provide safety traits (readOnly, idempotent), so description adds valuable behavioral 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?

Two sentences plus a bulleted use-case list. Every sentence adds value, no redundancy. Front-loaded with core purpose.

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

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

Covers purpose, output format, and use cases adequately for a simple tool with full annotations. Lacks mention of error handling or invalid URLs, but not critical for selection.

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

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

Schema description coverage is 100% with detailed parameter descriptions. Description adds only minor context (e.g., 'default 25, max 50' for max_links) beyond schema, 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?

Description clearly states verb 'Generate', resource 'llms.txt file', and context 'for any URL so AI crawlers can index the site cleanly'. It differentiates from siblings by specifying a unique output format and use case.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor AI visibility. Lacks explicit when-not-to-use or alternatives, but use cases are clear and distinct from siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the specific return fields but no additional behavioral traits beyond what annotations provide.

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

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

The description is a single concise sentence that is front-loaded with the key action and resource. No unnecessary 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?

For a simple tool with one parameter, good annotations, and an output schema, the description adequately covers purpose, input, and output without needing further details.

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

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

Schema coverage is 100%, so the parameter is fully documented. The description reiterates the hash types but adds no new 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 retrieves metadata for a malware sample by hash, listing specific return fields. This distinguishes it from sibling tools like search_family or search_signature by focusing on hash-based lookup.

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

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

The description implies use when you have a hash, but does not explicitly state when to use this tool over alternatives or provide exclusion criteria.

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, destructiveHint=false, idempotentHint=true. Description adds return field details and scope ('caller's subscriptions'), no contradictions.

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

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

Two sentences plus a usage line, no wasted words. Information is front-loaded: purpose first, then returns, then usage guidance.

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

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

Given no output schema, the description lists return fields and gives usage guidance. It is sufficient for a simple list tool, though lacks pagination or limit details, which are not critical.

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 parameter 'include_inactive' is fully documented in the schema. Description does not add further meaning beyond the schema, 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 'List the caller's active subscriptions' with specific verb and resource, and lists return fields. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises using it 'to review what you're monitoring before adding more or to find an id to cancel,' providing context for when to use. Could be more explicit about when not to use, but it implicitly points to subscribe/unsubscribe.

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 annotations (which only say not read-only, not destructive), the description discloses rate limiting (5/day), the claim_token flow for later retrieval, and the instruction not to paste end-user prompts. It also states that filing without an account returns a token, adding concrete behavioral context.

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

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

The description is longer than typical, but every sentence serves a distinct purpose: purpose, triggers, exclusions, message guidance, token mechanics, rate limit, and quota. It is logically structured, front-loaded with the core purpose, and contains no redundancy or filler.

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

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

For a tool with 4 optional parameters and no output schema, the description is fully self-contained: it explains what the tool does, when to use it, what not to do, how to use the returned claim_token, rate limits, and even roadmap impact. There are no significant 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%, so the baseline is 3. The description adds value beyond the schema: for `message` it specifies 'describe in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and for `claim_token` it provides exact usage syntax and behavior. These enrich the parameter understanding, though the schema already carries much of the load.

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

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

The description opens with a specific verb+resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It clearly distinguishes this feedback tool from the many research/search siblings by stating its unique role. The title and description align perfectly.

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

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

Provides explicit usage triggers for each feedback type (bug, feature, data_gap, praise) and an explicit exclusion: not for tools from other MCP servers. It even gives a decision heuristic ('Pipeworx tool names are the ones this connection lists') and directs users to file elsewhere for non-Pipeworx 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral traits: self-aggregating signal, no PII, and caching window (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 and well-structured, using bullet points for use cases. Every sentence adds value with no redundancy. Ideal length for this tool.

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

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

For a simple read-only tool with one parameter, the description covers purpose, use cases, return content, and caching behavior. No gaps remain given good annotations and 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 one parameter (window) having enum and description. The description adds meaning by explaining that shorter windows surface 'hot right now' vs longer windows show 'steady-state demand', which goes beyond the schema.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window' with specific use cases. It distinguishes itself from sibling tools by focusing on trending/aggregate data rather than individual 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 provides three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment). It does not explicitly mention when not to use or compare to siblings, but the context is clear and helpful.

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 readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: algorithmic details (monotonicity, partition checks, Jaccard similarity, placeholder filter, fill check against CLOB depth), response structure, and trading advisories (e.g., realizable_edge_pp ≤ 0 means don't trade). 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 front-loaded with the core purpose and mode guidance. It is dense with information but well-organized. Some algorithmic details could be streamlined, but it remains efficient given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities array with fields, partition_check, fill_check). It covers edge cases (placeholder filter, Jaccard similarity, CLOB depth check). For a complex arbitrage tool, the description is remarkably complete.

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

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

Schema covers 100% of parameters with descriptions, but the description adds significant value: explains when to use each parameter (event for specific market, topic for cross-event scanning), provides examples of slugs and seed questions, and details behavioral differences between modes.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, 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 explicitly advises when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains cross-event mode catches patterns that single-event misses. However, it does not explicitly contrast with sibling tools like polymarket_edges, though it references polymarket_fill_risk for custom sizing.

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

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

The description provides extensive behavioral details beyond annotations: caching at KV level with 1h TTL, internal model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with specific calculations, response structure including diagnostics like 'filter_skips' and 'fed_candidates'. No contradiction with annotations (readOnlyHint, idempotentHint, 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?

Description is well-structured with clear sections (model families, response fields, knobs, caching) and front-loads the purpose. However, it is somewhat verbose with many technical details; could be trimmed slightly without losing essential information.

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

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

Given 9 parameters and no output schema, the description covers all necessary aspects: model families, edge calculations, response segments (by_segment), diagnostic information, and caching behavior. It enables an agent to fully understand the tool's capabilities and limitations.

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 meaningful context: explains why min_kelly only applies to single-leg opportunities, gives rationale for slippage_pp default (20-50bp), and clarifies min_partition_leg_kelly's role for partition legs. This adds enough value to warrant a 4.

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

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

Description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also provides the use case ('what should I bet on today') and distinguishes from siblings like polymarket_arbitrage by emphasizing Pipeworx data disagreement.

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?

Description explicitly states the tool is built for discovering daily betting opportunities without paging through hundreds of markets. It mentions tradeable-edge knobs (min_liquidity, max_spread_pp) that filter when opportunities are not realizable. However, it does not explicitly exclude when not to use or compare with alternative siblings.

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

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

Annotations already declare the tool is read-only and non-destructive. The description adds rich behavioral details: response structure (tracked[], expired[], snapshot_dates[]), sign meaning, decay computation, cache-miss gaps, and median lifespan. No contradictions with annotations.

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

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

Description is well-organized with clear sections (RESPONSE, LIMITS) and front-loaded with the key question. It is slightly verbose but every sentence adds value. 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?

Without an output schema, the description thoroughly explains the return format and fields. It covers limits and snapshot gaps. Lacks error handling or permission requirements, but for a read-only tool with annotations, it is sufficient.

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 description adds minimal extra meaning. It clarifies 'days' max as 30 (schema says clamp 2-30) and 'window' as 'snapshot family', but schema already documents values. Benefit is marginal.

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' and answers a specific trading question. It distinguishes from sibling tools like 'polymarket_edges' by focusing on the time-series behavior of edges, not just current snapshots.

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

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

The description gives context on why edge persistence matters ('a fresh wide edge and a 3-week-old wide edge are different trades') and mentions limits (60-day TTL), but does not explicitly state when NOT to use this tool or name alternative tools for current edge data.

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, etc. The description adds valuable behavioral context: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and for basket mode details per-leg fill detail, thin_legs, forced_directional_risk. 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 relatively long but well-structured using uppercase headings (SINGLE-MARKET, BASKET) and bullet-style lists. Every sentence provides essential information, though a bit more conciseness could be achieved without losing clarity.

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

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

Given the tool's complexity (dual modes, multiple return fields, no output schema), the description is exceptionally complete. It covers required parameters, return values for both modes, defaults, warnings about risks, and even implications for partial fills. No gaps identified.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond the schema: it explains the difference between single-market and basket modes, the interpretation of size_usd (spend vs target proceeds vs settlement notional), default side logic for basket, and clamp ranges. This information is critical for correct usage.

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

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

The description clearly states the tool's purpose: a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, and explains what each mode returns, making it distinct from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use this tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It also explains that theoretical overround on thin books is not capturable, implying when not to rely on theory alone, and highlights risks like partial basket fills converting arb into unhedged directional positions.

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 readonly, open-world, idempotent, non-destructive. Description adds rich behavioral context: safety fields (compatibility_warning, temporal_alignment), interpretation of skipped_cross_type, and confirms readonly nature. No contradictions.

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

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

Description is relatively long but packed with useful information. It is front-loaded with purpose, then modes, response, safety. Could be slightly trimmed but not wasteful.

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 explains the response structure (leg-by-leg prices, spread[], compatibility_warning, temporal_alignment, counters). It comprehensively covers edge cases and result interpretation.

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

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

Schema has 100% description coverage for all three parameters. The description adds further meaning: explains modes, how topic is overridden by explicit parameters, and provides examples with acceptable values.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers), and is specific about what it does, differentiating it from all sibling tools.

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

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

The description tells when to use topic vs explicit modes, and warns that real spreads are rarer and pre-mapped doesn't guarantee tradeability. It provides guidance on interpreting results, though 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping (to identifier) and listing 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 three well-structured sentences, front-loaded with main purpose, then usage and pairing. No redundant or wasted words.

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

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

Given the tool's simplicity (one optional param, no output schema), the description fully explains what the tool does, when to use it, and its scope.

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

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

Schema coverage is 100% for the single optional parameter. The description adds context: omitting the key lists all keys, which is not in the schema description.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. It distinguishes from sibling tools remember and forget, providing a specific verb and resource.

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

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

The description explicitly states when to use the tool: 'look up context the agent stored earlier... without re-deriving it from scratch.' It also explains behavior when omitting key and mentions pairing with remember and forget.

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

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

Annotations declare readOnlyHint=true, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' implying a state change on the server. This contradicts readOnlyHint. While the description adds context about returned data and polling, the contradiction undermines transparency.

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

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

The description is a few concise sentences without fluff. It could be slightly more structured (e.g., bullet points), but overall efficient.

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

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

Given high schema coverage and annotations, the description covers return format, filtering, mark_read, and alternative access. However, the contradiction with annotations reduces completeness as the described behavior may mislead.

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 examples (type filter, ISO timestamp) and explains mark_read behavior, but does not significantly augment the schema descriptions.

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

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

Clearly states the tool pulls fired events from subscription feed, returning recent alerts with source, citation_uri, and raw payload. The verb 'Pull' and resource 'fired events from your subscription feed' are specific and distinct from sibling tools like recent_changes or recent_samples.

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 good usage guidance: filters by type (e.g., 'sec_8k') and/or since (ISO timestamp), explains mark_read for tracking read state, and mentions polling works fine with an alternative URL. However, it does not explicitly differentiate from sibling tools or state when not to use this 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 mark as read-only/idempotent; description adds details about fan-out to multiple sources, fallback logic, soft-fail for USPTO after May 2025, and return structure (changes[] grouped by source).

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

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

Dense paragraph front-loaded with example queries, then sources, parameters, and alternative tool. Well-organized but could be slightly more concise.

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

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

No output schema; but description explains return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs), covers limitations (USPTO soft-fail), and mentions alternative tool. Complete for a 3-param 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% (baseline 3). Description adds context: 'since' accepts ISO or relative shorthand with typical usage recommendation, 'value' clarifies ticker or CIK, 'type' explains only company is supported.

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 retrieves changes (SEC filings, news, patents) for a company in a time window, provides example queries like 'What's new with X', and distinguishes from sibling 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 tells when to use this tool vs entity_profile, provides parameter recommendations (e.g., 'Use "30d" or "1m" for typical monitoring'), and explains fallback behavior (GDELT preferred, GNews when rate-limited).

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 false, so the description's claim of retrieving recent samples is consistent. It adds minor behavioral context (chunk size via selector) but does not disclose details like ordering or time window interpretation, which are partially in schema.

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

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

Two concise sentences with front-loaded purpose and no extraneous words. Every sentence provides value.

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

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

Given an output schema exists and annotations cover safety, the description is minimally adequate but lacks context about how recent samples are ordered or when to prefer this over siblings like 'get_sample_info' or 'search_tag'.

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 clear enum and default. The description adds only 'pick a chunk size', which adds minimal value 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 provides 'most recent samples in MalwareBazaar', but does not explicitly use a verb like 'retrieves' or 'lists'. It is distinguishable from sibling tools like 'get_sample_info' or 'search_family' only by context; no differentiation is provided.

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?

No guidance on when to use this tool versus alternatives. The description only mentions using a selector for chunk size, without stating when not to use it or referring to 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?

Describes storage as key-value pair scoped by identifier, mentions persistence (authenticated vs anonymous 24 hours), and is consistent with annotations: idempotentHint=true (overwrite), readOnlyHint=false (write), destructiveHint=false (non-destructive). 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?

Concise 5-sentence paragraph that front-loads the main purpose, then adds usage context and technical details without unnecessary 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?

Covers purpose, usage guidelines, persistence behavior, parameter semantics, and sibling tool links. No output schema needed for a store operation, and the description provides complete context for agent 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 covers both parameters with descriptions, and the description adds contextual examples for key values (e.g., 'subject_property') and what values can contain. Provides meaningful usage guidance beyond schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' across conversations or sessions. It provides specific examples like 'resolved ticker, target address' and distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward so you don't have to look it up again.' It also mentions pairing with recall to retrieve and forget to delete, providing clear 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 goes far beyond the annotations by disclosing key behaviors: graceful degradation of LEI/FIGI enrichment when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers under an `unresolved` field rather than omitting them, source-labeling of every identifier, and internal cascading through multiple lookup endpoints. These details align with the read-only/idempotent annotations and add substantial context.

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

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

The description is lengthy, but it is well-structured: it opens with natural-language query examples, clearly marks the supported types section, and includes caveats at the end. Each sentence contributes meaningful guidance, though the user-phrase list could be trimmed slightly without losing intent-matching value.

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

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

Given the tool's moderate complexity and lack of an output schema, the description provides a thorough account of what the tool returns: canonical identifiers from specific sources, source labels, explicit `unresolved` fields, and graceful degradation behavior. It also covers accepted input forms for both entity types, making it sufficiently complete for an agent to decide when to invoke and what to expect.

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

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

The input schema already provides 100% coverage with descriptions for both parameters, including the enum for `type` and examples for `value`. The description mostly repeats these examples (ticker, CIK, name; brand/generic drug name) and adds contextual behavior rather than new parameter-specific semantics. Thus it meets the baseline but does not significantly enhance parameter understanding 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's purpose with a specific verb and resource: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It distinguishes itself from sibling tools by emphasizing it is the first stop when you have a name but need an ID, and it enumerates supported entity types (company, drug) and the identifiers produced (CIK, LEI, FIGI, RxCUI).

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

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

The description gives an explicit usage directive: "Use FIRST whenever you have a name but need an ID." It also explains that it replaces 2-3 manual lookups, which clarifies its intended role. However, it does not explicitly state when not to use it or mention alternative sibling tools for cases where you already have an identifier.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is transparent. Description adds that it probes each entity, ranks by score, and returns a ranked list with score, confidence, signal density, fully explaining the behavior 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?

Description is three sentences, front-loaded with the core action, immediately followed by purpose and example. No redundant or extraneous information; 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?

Input schema is fully documented, annotations cover safety, and description details the return format (ranked list with score, confidence, signal density). No output schema exists, but description sufficiently explains what to expect, making the tool complete for its complexity level.

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 provides high-level context for parameters (e.g., 'first entry treated as subject', 'context disambiguates'), but these details are already present in the input schema descriptions, adding no new meaningful information beyond what the schema provides.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally and ranking results. It distinguishes itself by targeting competitive audits, which is specific and different from sibling tools like ai_visibility_check (single 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?

Explicitly states the tool is for competitive AI-marketing audits and gives an example query. It implies single-entity checks should use ai_visibility_check, though doesn't explicitly list alternatives. Guidance is clear for when to use.

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

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

Discloses partial failures, bundlephobia measurement delay (5-30s), and sources_failed behavior. Annotations already provide readOnlyHint, but description adds valuable operational context.

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

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

Dense but well-structured; front-loads purpose and usage. Could be slightly trimmed but uses every sentence to add 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?

Describes return format (summary block, advisories, links, alternatives) despite no output schema. Covers error handling and performance characteristics.

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; description adds that scoped packages are accepted and version defaults to latest, providing extra clarity beyond schema properties.

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 composite check for npm packages, combining deps.dev and bundlephobia data. Specifies ecosystem (npm only) and distinguishes from sibling tools like ask_pipeworx or deep_research.

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

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

Explicitly says when to use: when agent asks about safety, popularity, size. Also notes alternatives for non-npm ecosystems via deps.dev:version.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints. The description adds value by detailing the returned fields (hashes, file type, dates, tags, intel sources) and the 'how recently' recency context, which goes beyond the annotation metadata.

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 long, with the core action front-loaded. It efficiently explains the function, examples, outputs, and user-facing value without 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?

With an output schema present and annotations rich, the description covers the essential aspects: the data source, the search criterion, result contents, and the time-related question it answers. No critical missing context for a read-only search tool.

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

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

Schema coverage is 100% with both 'family' and 'limit' already described. The description clarifies 'family' as a signature name, but this is marginal. According to the baseline for high schema coverage, a score of 3 is appropriate as the description adds little beyond the schema.

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

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

The description clearly states the tool looks up malware samples by family or signature name, with specific examples (Cobalt Strike, AgentTesla). It differentiates from sibling tools like search_signature and search_tag by focusing on family attribution and specifying the data source (MalwareBazaar).

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 establishes clear context for when to use this tool: to find samples of a named malware family and see submission recency. It doesn't explicitly name alternatives like search_tag, but the focus on family/signature distinguishes it from siblings without ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond this, such as rate limits or authentication needs.

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

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

A single, well-structured sentence that conveys the tool's purpose without extraneous words. Ideal conciseness for a simple tool.

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

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

Given the tool's simplicity, 100% schema coverage, and presence of an output schema, the description is complete enough to allow correct selection and invocation.

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

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

Schema description coverage is 100%, so the schema adequately documents both parameters (signature and limit). The description adds no additional parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool finds samples matching a YARA or threat-intel signature, using specific verb and resource. It distinguishes from sibling tools like search_family or search_tag by focusing on signatures.

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?

No guidance is provided on when to use this tool vs alternatives (e.g., search_family, search_tag). The description only states what it does, leaving the agent to infer usage 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 cover the read-only, idempotent, and non-destructive nature. The description adds valuable context beyond annotations by specifying that it queries MalwareBazaar, returns only recently submitted samples, and lists exact return fields. It does not delve into rate limits or pagination, but the bar is lower given strong 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 long, front-loaded with action and resource. The first sentence immediately states what the tool does; the second sentence efficiently enumerates the return fields and the core question answered. 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 existence of an output schema and strong annotations, the description covers the key aspects: source, query method, and return contents. The only minor gap is the ambiguous 'recently submitted' time window, but this is a small omission in an otherwise complete description.

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

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

Schema coverage is 100% and the schema already describes both parameters, so baseline is 3. The description enriches the tag parameter with concrete examples ('emotet', 'macro', 'exe', 'ransomware') that help an agent understand valid values. It does not add explicit detail for limit beyond schema, but the examples provide meaningful semantic value.

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

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

The description uses the specific verb 'Look up' and clearly identifies the resource: malware samples in MalwareBazaar carrying a given tag. It provides concrete tag examples ('emotet', 'macro') and distinguishes the tool from siblings like search_family and search_signature by focusing on tag-based lookup.

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

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

The description implies usage for finding samples by tag but provides no explicit when/when-not guidance or references to alternative tools such as search_family or search_signature. There are no exclusions, but also no clear direction on choosing this tool over siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: truncation at 200K chars with a flag, use of BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and character offsets. 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 somewhat long but efficiently packs essential information. The first sentence states the core purpose, and subsequent sentences add valuable detail. Slightly more conciseness would improve it, but it is well-structured.

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

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

Given that there is no output schema, the description hints at return values (passages with offsets and similarity scores) but does not specify format. Considering the tool's complexity (embeddings, truncation, offsets), the description is largely complete.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra context beyond the schema: text max size, limit default, and query examples. This adds meaning but is not strictly necessary given the schema's thoroughness.

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 specifies a specific verb ('search inside') and resource ('a fetched record'). It clearly distinguishes itself from siblings by describing its pairing with ask_pipeworx_grounded, establishing its unique role among many tools.

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

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

The description provides clear usage context: 'when the record is too big to cram into the prompt.' It also explains how it pairs with another tool. However, it does not explicitly state when not to use it or list alternatives beyond the mentioned pairing.

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

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

The description adds significant behavioral context beyond annotations: it details the required account type, the always-on feed, email/SMS/webhook delivery with specific constraints (SMS cap, webhook auto-disable, HMAC signing), and the return of a subscription id. 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 concise (4-5 sentences) and front-loaded with the main purpose. Every sentence adds necessary detail without redundancy. Well-structured: purpose, result, requirement, types, delivery channels.

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

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

Given 3 parameters (nested), no output schema, the description covers the return value (subscription id), all delivery channel behaviors, and type-specific parameters. It does not mention error cases, but the level of detail is high enough for an agent to use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description enhances each parameter with concrete examples (e.g., 'items:["5.02"]', 'topic:"fed"', 'series_id:"UNRATE"') and clarifies constraints like 'sms must match verified phone' and 'webhook HTTPS only'. This adds value beyond the schema.

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

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

The description starts with a clear verb-resource pair: 'Create a proactive monitoring subscription to a live-data event stream.' It explicitly mentions returning the subscription id, and the name 'subscribe' combined with sibling names like 'unsubscribe' and 'list_subscriptions' differentiates this tool clearly.

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

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

The description includes prerequisites ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'), lists supported types with examples, and mentions delivery channel options. It does not explicitly state when not to use or name alternatives, but the context is sufficient.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. The description adds value by describing the return format (example questions with tool+argument shape) and the fact that it draws from a live catalog, beyond what annotations provide.

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

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

The description is slightly long but well-organized with alternative questions up front, then explanation of output and parameters. Every sentence is informative, though minor trimming could be possible.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, parameter behavior, and output nature, making it complete for onboarding.

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 parameter description is clear. The description adds extra meaning by listing specific topic values and explaining the effect of omitting vs. providing the topic, which helps the agent use the tool correctly.

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

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

The description clearly states the tool returns category-bucketed example questions, serves as an onboarding entry point, and distinguishes itself from siblings by being the first tool to use when exploring Pipeworx's capabilities.

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 this FIRST when you do not yet know what Pipeworx can do for you' and describes when to pass a topic vs. call with no arguments, providing clear context of 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds important behavioral context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This explains the non-destructive nature and data retention policy.

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

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

The description is three concise sentences with no wasted words. It front-loads the core purpose first, then adds constraints and behavioral details efficiently.

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 purpose, constraint, and behavioral nuance. It omits explicit return value details, but given the simplicity and idempotentHint, the context is mostly complete. A minor gap is not explaining the response format.

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 parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' but adds no new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', using a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by describing the cancel action.

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'), providing a clear usage constraint. It does not explicitly name alternatives but contextually implies when not to use it.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds crucial behavioral context: the distinction between could_not_verify and unsupported, the verification_error{stage,detail} structure, and the fact that it replaces multiple sequential calls. This goes well beyond what annotations provide.

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

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

The description is well-structured: it starts with naturals examples, states the core purpose, then explains the routing, return values, and special cases. Each sentence earns its place, and the formatting makes it easy to scan.

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

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

Even without an output schema, the description fully explains the return verdicts, evidence with citations, and reasoning. It also covers error handling for could_not_verify, the difference from unsupported, and the efficiency benefit, making the tool's behavior completely understandable.

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

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

Schema coverage is 100% and both parameters are described in the schema. The description adds value by explaining tolerance_pct semantics: it overrides the implied tolerance, suggests 1–2 for hallucination detection, and defaults to wording-based cap of 5. This enriches the schema without redundancy.

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 performs natural-language claim verification against authoritative sources, with specific examples like 'fact check' and 'verify the claim that…'. It distinguishes itself from sibling tools by noting it replaces 4–6 sequential calls and focuses on fact-checking rather than general research.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two paths (SEC EDGAR for company-financial claims vs. grounded pipeline for others). It doesn't name alternatives or exclusions, but the context makes the intended use clear.

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