Sec Regulations

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) already indicate safe, idempotent read behavior. The description adds valuable context: default model is Workers AI (free), Anthropic requires a BYO key passed to api.anthropic.com, and returns per-model details. It does not mention rate limits or potential cost implications beyond the API key, but overall adds significant behavioral context beyond annotations.

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

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

The description is four sentences, front-loaded with the primary purpose and key details. Every sentence adds essential information: purpose, default model, optional Anthropic with cost note, and output structure. No filler or redundancy.

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

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

The tool has no output schema, so the description compensates by stating: 'Returns per-model {score, confidence, signals, raw_response} + a combined view.' This is sufficient for understanding the output. For a simple 4-parameter probing tool, the description covers the necessary aspects. Minor improvement could detail what 'signals' or 'combined view' contain, but 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 description coverage is 100% with clear descriptions for each parameter. The description adds value by: giving examples for entity (e.g., 'Pipeworx', 'OpenInvoice'), clarifying that models defaults to workers-ai, explaining that _apiKey is only needed if 'anthropic' is in models, and that context helps disambiguate. This goes beyond the schema, though the schema already does a good job.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb (probe, score), resource (LLMs), and output format. This distinguishes it from sibling tools like 'ask_pipeworx' (general Q&A) and 'scan_competitor_ai_presence' (different scope).

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use the optional _apiKey for Anthropic. However, it does not explicitly mention when NOT to use this tool or list alternatives among siblings, which would improve score to 5.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals important behavior: it auto-routes the question, fills tool arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes a single fast call. This gives the agent an accurate mental model of what happens when the tool is invoked.

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

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

The description is long but every sentence earns its place: it front-loads the most critical routing advice, gives concrete examples, clarifies the default status, and names the alternatives with conditions. It is well-structured and information-dense without being redundant.

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

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

Despite having no output schema, the description compensates by explaining what the output looks like: a structured answer with stable citation URIs. It also covers input expectations, scope, fallback tools, and tier availability, so an agent has enough context to invoke the tool correctly and interpret the result.

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 documents the question parameter plus all aliases. The description adds useful examples of natural-language questions, but it does not need to explain parameter semantics further because the input schema fully carries that burden.

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

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

The description clearly defines ask_pipeworx as the default entry point for factual and real-world data questions, explaining that it routes to thousands of tools and returns structured answers with citation URIs. It also explicitly differentiates it from ask_pipeworx_grounded and deep_research, giving the tool a unique and unmistakable role.

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 when-to-use guidance, including 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and common query patterns. It also gives when-not-to-use conditions by directing hallucination-sensitive asks to ask_pipeworx_grounded and broad multi-part research to deep_research, making the routing decision clear.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive; the description adds meaningful context by stating this is a full working router, not a fallback, that candidate improvements may be live, and that results are compared against the stable router. 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?

Three sentences are front-loaded with the core definition and sibling relation, then current status, usage direction, and a clarification. Slightly repetitive ('identical...matches exactly' and 'full working router') but each sentence serves a distinct purpose.

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

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

For a complex router with no output schema, the description covers current active state, usage equivalence, and the fact that it is a complete working tool. It references the same response shape as ask_pipeworx, which is a useful pointer, though it doesn't spell out the return format itself.

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 all six parameters (question plus five aliases) are documented in the schema. The description only says 'same arguments' and adds no syntax or format detail 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?

Describes the tool as the beta variant of ask_pipeworx, an identical universal router over 5,798 tools with the same arguments and response shape. This clearly distinguishes it from the stable ask_pipeworx sibling while explaining what it does; the only weakness is relying on the reader knowing what ask_pipeworx itself does.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when you want the newest routing, and explains the current experimental state (no active candidate). It doesn't list exclusion cases or mention ask_pipeworx_grounded, but it gives a clear selection condition relative to the stable sibling.

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 carry the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond that: the internal routing mechanism across 5,798 tools / 1517 sources, the verbatim-evidence requirement, the structured return envelope, and an explicit refusal protocol with five named refusal reasons. It also discloses the extra-cost trait, which no annotation could express.

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?

Front-loaded with the core purpose, then flows logically through routing, return envelope, refusal contract, use cases, and cost tradeoff. It is dense, but every sentence contributes distinct information; the refusal_reason enum is the most expendable section, yet it is justified given there is no output schema to document it elsewhere.

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

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

For a single-parameter, fully-annotated, read-only tool with no output schema, the description is complete: return shape, refusal contract, sibling tradeoff, decision criteria, and cost behavior are all covered. An agent can select and invoke this tool correctly without additional lookups; at most one could wish for the confidence-value scale, which is minor.

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 fully documents the single required parameter 'question' along with its five aliases. The description does not add parameter-format details — the 'picks the right tool... fills arguments' line describes internal routing behavior rather than parameter semantics. The baseline 3 applies since the schema does the heavy lifting.

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

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

The description opens with a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It then names the closest sibling (ask_pipeworx) and explains the exact differentiator — same routing but extraction using ONLY what the tool result contains. This makes it immediately distinguishable from ask_pipeworx, ask_pipeworx_beta, and the other 27 siblings.

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

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

Provides explicit when-to-use criteria: 'whenever an answer will be quoted, cited, or acted on' with concrete high-stakes domains (financial verdicts, legal claims, medical lookups, public statements). It also gives the when-not-to-use case: 'prefer ask_pipeworx for casual lookups,' backed by a concrete cost rationale (one extra LLM call). Selection requires zero inference.

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, idempotentHint, destructiveHint) are complemented by extensive behavioral details: resolution process, classifier system, fan-out examples, response shape, resolver contract, safety mechanisms (low-confidence, closed markets, wide spreads), and resolution-rule risk. No contradictions with annotations.

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

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

The description is lengthy and contains verbose sections (e.g., fan-out examples, resolver contract). While structured with section headers, it could be more concise. However, the complexity of the tool justifies most content, so it is not severely bloated.

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

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

Given the complexity (3 parameters, no output schema), the description is exceptionally comprehensive, covering input formats, internal behavior, response fields, edge cases, and safety notes. An agent can fully understand the tool's capabilities and limitations 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%, and the description adds significant value beyond schema: explains the 'depth' enum ('quick' vs 'thorough' with definitions), clarifies the 'market' parameter accepts three formats, and details 'include_raw' behavior (summarized vs full payloads). Examples further enhance 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 first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and method. The description also lists supported input types (slug, URL, question text), 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 recommends usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It implies this is the primary research tool but does not explicitly mention when to avoid it or refer to sibling tools as alternatives, leaving some room for improvement.

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

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

Description adds value beyond annotations: details parallel call behavior, off-calendar fiscal year handling, sorted results, data sources (SEC, FAERS), and citation URIs. 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 front-loaded with query examples and is dense with useful information. Slightly long but every sentence earns its place; no fluff.

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

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

For a tool with two entity types, multiple data sources, and no output schema, the description covers return format (paired data, citation URIs) and sorting behavior. Adequate for informed use.

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

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

Schema coverage is 100%. Description enriches parameter meaning with examples ('AAPL', 'ozempic') and specifics (10-K financials for companies, FAERS counts for drugs), beyond the schema's enum and array constraints.

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

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

Description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, with example queries and specific data pulled per type. Distinguishes from sequential 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?

Explicitly prefers this tool over sequential lookups for comparisons. Provides context (compare, rank, head-to-head). No explicit exclusions, but alternatives are implied via sibling tools like entity_profile.

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

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

Beyond the readOnly/idempotent annotations, the description discloses rich behavior: parallel tool routing, findings packet fields, gaps[] for unanswered facets, 'never invented' wording, hop field, resolvable citation_uri, contradictions[] for standard/thorough, semantic excerpting, and latency expectations. This goes far beyond what annotations provide.

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

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

The description is long but densely informative; nearly every sentence carries decision-relevant detail. It is front-loaded with account requirements and the primary alternative. Slight redundancy in repeated ask_pipeworx mentions keeps it from a 5, but the length is justified by 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?

Given there is no output schema, the description fully explains the return shape: verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[] and hop field. It also covers prerequisites, depth tiers, latency, and when-not-to-use, making it complete for an agent to invoke this tool correctly.

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

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

Schema already covers 100% of parameters with meaningful descriptions. The description adds value by elaborating on depth behavior — 'standard re-angles unanswered gaps', 'thorough additionally chases the best leads' — and by clarifying the question parameter accepts broad/multi-part natural language, which the schema only implies.

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

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

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' with parallel decomposition into facets. It explicitly differentiates itself from siblings by saying 'this is NOT open-web search' and naming when ask_pipeworx is the right tool instead.

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 routing guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx instead', and 'For BREAKING or CURRENT news... prefer ask_pipeworx'. It also declares its best-fit use case: 'Best for broad/multi-part questions over structured 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 indicate readOnlyHint=true and idempotentHint=true; description adds that results are ready to call directly without extra schema lookup and returns curated examples. 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 informative but somewhat verbose, listing many domains and details. Front-loaded with core purpose, but could be tightened 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?

No output schema, but description explains return format (top-N tools with names, descriptions, schemas) and usage advice. Missing output schema is not critical here.

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. Description adds examples and lists aliases (task, q, search, description), providing practical usage context 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 finds tools by describing data or task, lists many example domains, and specifies it returns top-N relevant tools with full schemas. This differentiates it from other tools like search_within 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 advises 'Call this FIRST when you have many tools available and want to see the option set'. Provides context for browsing/discovering tools, though it doesn't explicitly mention 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?

The description adds substantial behavioral detail beyond the readOnly/openWorld/idempotent annotations: fan-out across many sources, USPTO soft-failure, 'sources_used/sources_failed' semantics, empty-sections-meaning-no-data, and resolved:false for private companies. No contradiction with annotations.

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

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

The description is long but front-loaded with trigger examples and the one-call advantage. It is dense and mostly non-redundant; the extended detail is largely justified by the absence of an output schema, though some schema-level type/value repetition could be trimmed.

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

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

For a complex multi-source tool with no output schema, the description covers output shape, source list, fallback behavior, edge cases, and failure semantics. An agent has enough context to invoke it correctly and interpret results.

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

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

Schema description coverage is 100%, so the schema already fully explains both parameters. The description reinforces this with examples and the note that type/value are interchangeable, but it adds no parameter-level meaning 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 states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' It also gives concrete trigger phrases and explicitly contrasts itself with chaining single-pack SEC/XBRL/news lookups, making its purpose unmistakable.

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

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

It gives an explicit when-to-use rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also documents acceptable input forms and the private-company edge case, but it does not explicitly name sibling tools like resolve_entity or compare_entities as alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about usage scenarios but no additional behavioral details (e.g., error handling, outcomes).

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

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

Extremely concise: one sentence for purpose, a list of usage contexts, and pairing info. 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 and no output schema, the description covers purpose, usage, and relationships. No gaps.

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

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

Schema coverage is 100% and the schema description for 'key' is sufficient. The tool description adds no extra meaning beyond 'by key'.

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 verb 'delete', the resource 'memory', and the method 'by key'. It distinguishes from sibling tools like '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 states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with alternatives.

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

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

Annotations indicate read-only, non-destructive, idempotent. Description adds detail: fetches page, extracts content, emits markdown format. 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?

Single paragraph, front-loaded with purpose, then process, output, use cases. Every sentence adds value, no redundancy.

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

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

Covers input, process, output format. Lacks error handling or edge cases, but given simple 2-param tool, still 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 covers both parameters with descriptions (100% coverage). Description does not add additional semantics beyond what 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 it generates an llms.txt file for AI crawlers from a URL. The verb 'generate' plus resource 'llms.txt' make purpose distinct from sibling tools.

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

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

Explicit use cases provided (client's site, own project, auditing competitor). No direct exclusions or alternatives mentioned, but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by listing return fields and implying the default list is active subscriptions, but does not elaborate on limits or pagination.

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 efficient sentences: first covers purpose and output, second provides usage guidance. No extraneous 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?

Adequate for a simple list tool with one optional parameter. Lacks mention of empty list behavior or details on fields like 'fire_count', but overall sufficient given annotations and sibling tools.

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

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

Schema coverage is 100%, so baseline 3. The description does not add meaning beyond the schema—the parameter 'include_inactive' is only described in schema.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates the returned fields. It distinguishes itself from siblings like 'subscribe' and 'unsubscribe' by focusing on listing, not modifying.

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: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and alternatives.

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

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

Annotations are minimal (four false hints), so the description carries the burden and does it thoroughly. It discloses that filing without an account returns a claim_token for later lookup, that the team reads digests daily, that feedback affects roadmap, that it is rate-limited to 5 per identifier per day, and that it is free and doesn't count against quota. This goes beyond annotations and provides meaningful 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 front-loaded with the core purpose and flows logically through when-to-use, exclusions, workflow, and constraints. It is denser than typical but every sentence adds value. Slight deduction for length and the parenthetical aside about tool names being the ones listed by the connection, which could be more concise.

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

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

This is a feedback submission tool with no output schema, so the description must fully explain behavior and outcomes. It covers what happens on filing (claim_token), how to check resolution, team response cadence, rate limits, and quota effects. For a tool with 4 parameters and no required fields, this description fully prepares an agent to use it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant value beyond the schema. It explains the exact semantics of claim_token usage (pass pwfb_… with no other arguments to check status), describes message content expectations (be specific, 1-2 sentences, 2000 chars max), and clarifies the type enum values. This substantially enriches the parameter 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 clearly states the tool's purpose: sending feedback to the Pipeworx team about broken, missing, or needed functionality. It specifies distinct feedback types (bug, feature/data_gap, praise) and explicitly distinguishes itself from sibling tools by emphasizing it is ONLY for tools served by this Pipeworx connection, not other MCP servers.

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

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

Provides explicit when-to-use guidance: use for bugs, feature requests, data gaps, or praise. Clearly states when NOT to use it (for tools from other MCP servers) and directs users to file with that server instead. Also describes the workflow for claiming and checking feedback status via claim_token, plus rate limits and quota info.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h).

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 paragraphs. First sentence defines purpose. Then bullet-like use cases, followed by technical details. No unnecessary words, front-loaded with action and resource.

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

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

Given one optional parameter and no output schema, the description explains return values (top tools, packs, volume) and caching. Sufficient for agent to understand and 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 has 100% coverage with enum description. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. It provides three specific use cases and distinguishes itself from sibling tools as a trending data source.

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 (discovering hot data sources, confirming canonical tools, seeing alignment). Could be improved by mentioning when not to use it, but context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds deep behavioral context: partition checks, semantic anchor, partition filter, fill check, and response structure.

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

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

Long but well-organized with clear sections and examples. Could be slightly more concise, but every sentence adds value. Front-loaded with main 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 all modes, edge cases (semantic anchor, partition filter, fill check), and references sibling tool for custom sizing. No output schema, but response structure is explained.

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

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

Schema has 100% coverage, but description adds examples and explains the effect of each parameter (event vs topic). No enums, but thorough.

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

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

Clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools.

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

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

Explicit guidance on when to use each mode (no args, event slug, topic). Provides context for cross-event mode but lacks explicit 'when not to use' advice.

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?

Extremely detailed beyond annotations: explains the three model families with specific formulas (lognormal barrier, GDELT ratio, partition_overround with FLB correction, filter logic), caching behavior (1h at KV level), diagnostics for empty segments, and tradeable-edge knobs. No contradictions 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?

Well-structured with labeled segments and front-loaded purpose, but overly verbose (multiple paragraphs with intricate details). While comprehensive, it could be more concise for quick agent consumption.

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, description fully explains return structure (by_segment, fed_candidates, diagnostics) and all behavioral aspects (filtering, ranking, caching, segment emptiness reasons). Completely sufficient for an agent to understand and invoke the tool correctly.

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

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

Adds significant meaning beyond the 100% schema coverage: explains why each parameter matters (e.g., 'Set to 2 to require tight books'), relationship between min_kelly and min_partition_leg_kelly, and practical usage tips (e.g., slippage_pp default rationale).

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?

Clear verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' Explicitly states the tool's purpose and distinguishes from siblings by detailing its unique approach (three model families) and use case ('what should I bet on today').

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

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

Provides clear context for when to use (discover opportunities without paging) and detailed parameter guidance (knobs, filters), but does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, nor states 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 indicate readonly, open-world, idempotent, non-destructive. The description adds extensive behavioral context: data source (daily snapshots), trend computation, decay_pp_per_day meaning, limits (60-day TTL, daily closes), and response structure. No contradictions.

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

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

The description is lengthy but well-organized: purpose first, then output format, then limits. Every sentence adds value, though could be slightly more concise. Front-loaded with key purpose.

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

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

Given the complexity and absence of an output schema, the description thoroughly explains the return fields (tracked, expired, snapshot_dates) with field meanings and limitations. Complete for the tool's purpose.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining defaults, clamps, and the meaning of window (snapshot family), and details the response structure. Baseline 3, plus extra context.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it is shrinking. It distinguishes from sibling polymarket_edges by focusing on temporal analysis.

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 when to use it (e.g., to differentiate a fresh wide edge from an aged one), but does not explicitly state when not to use it or list alternatives. The contrast with polymarket_edges is implied but not direct.

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 (read-only, idempotent, non-destructive), the description details what the tool computes: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict. For basket mode, it explains 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?

Description is verbose but well-structured, with sections for SINGLE-MARKET and BASKET. Front-loaded with core purpose. Each sentence adds essential information for the two modes. Could be slightly trimmed but efficient given 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?

No output schema exists, so description must document return values. It does comprehensively: for single-market lists all output fields; for basket lists all output fields including thin_legs, forced_directional_risk. Covers edge cases and risks fully.

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

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

Schema coverage is 100%, but description adds critical meaning: explains market vs event modes, side parameter defaults and interpretation, size_usd difference between single-market (spend/proceeds) and basket (settlement notional). This goes well beyond the brief schema descriptions.

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

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

The description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. This differentiates it from siblings like polymarket_arbitrage and polymarket_edges, making the tool's unique role obvious.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing a clear when-to-use directive. It also warns about partial fills converting arb to directional risk, and requires either market or event parameter.

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 a read-only, idempotent operation, and the description goes well beyond them: it reveals that compatibility warnings can accompany matched pairs, defines each compatibility code, notes that unknown legs are never paired, clarifies that null temporal_alignment means 'could not compute,' and explicitly states that spreads are gross of Kalshi fees. This is thorough and honest behavioral disclosure with no contradiction.

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

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

The description is long but logically organized: purpose, modes, response shape, safety fields, fee disclosure, and skipped counters. Every section earns its place given the tool's complexity and the absence of an output schema, though the text could be tightened slightly without losing essential detail.

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 cross-venue comparison tool with no output schema, the description is remarkably complete. It names the important response fields, explains edge cases, defines all safety codes, and gives realistic expected-value guidance. An agent has enough information to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: `kalshi_event_ticker` and `polymarket_event_slug` override the topic-mapped sides, and both modes run the same token-overlap matcher. It also enumerates the valid `topic` shortcuts, which 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 states a specific operation: computing the cross-venue price spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from Polymarket-only sibling tools by emphasizing the two-venue comparison, and it names the two modes of use with concrete examples.

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 explains when to use the `topic` shortcuts versus explicit ticker/slug pairing, and it warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped is not tradeable. It does not name sibling alternatives, but the mode-selection guidance is otherwise clear and actionable.

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, non-destructive. Description adds value by explaining listing behavior on key omission and scoping to identifier, but doesn't add new behavioral traits beyond what annotations and schema imply.

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

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

Three sentences, front-loaded with the core action, no redundant words. Efficient and clear.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully complete: purpose, usage, scoping, and pairing with related tools.

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

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

Schema coverage is 100% and schema already describes 'omit to list all keys'. Description slightly rephrases but doesn't add new parameter meaning. Baseline 3 as schema does the heavy lifting.

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

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

The description clearly states the tool retrieves a value by key or lists all keys when omitted (verb+resource). It also distinguishes from siblings remember 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 to use for looking up previously stored context without re-deriving, mentions scoping and pairing with remember/forget. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint true, but the description adds that mark_read:true flags events as read, which is a state change. This contradicts the annotation but adds useful behavioral detail 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?

Three sentences with no waste. Front-loaded main action, then filtering, then mark_read and alternative access. Efficient and clear.

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

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

Covers return fields, filtering, mark_read side-effect, and alternative REST endpoint. Missing details on limit behavior and sorting, but parameters are well-described in schema. Adequate for a read tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical usage (e.g., type filter example 'sec_8k') and explains mark_read effect, but does not mention limit or unread_only (though they are in 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 verb 'Pull' and resource 'events from your subscription feed' are clear. It specifies return fields and filtering options, distinguishing it from sibling 'list_subscriptions' which lists subscriptions, not events.

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

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

The description gives context (polling works, alternative REST endpoint) and explains mark_read behavior. However, it does not explicitly state when to avoid this tool or compare with siblings like 'subscribe' or 'list_subscriptions'.

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, and destructiveHint=false. The description adds valuable behavioral details: fan-out to multiple sources, fallback mechanism (GDELT→GNews when rate-limited or 5xx), a known sunset issue (PatentsView API), and accepted date formats. 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 fairly long but front-loaded with example queries. Every sentence adds value, though it could be slightly more concise. The structure is logical, starting with usage examples, then the core purpose, then detailed behavior.

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

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

Given the tool's complexity (multiple data sources, fallback, date parsing) and the presence of rich annotations and schema, the description provides sufficient context. It explains the output shape (structured changes[] grouped by source + total_changes count + citation URIs) and clearly differentiates from sibling tools like 'entity_profile' and 'compare_entities.'

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%. The description adds meaningful context beyond the schema: for 'since,' it clarifies acceptable formats and recommends '30d' or '1m'; for 'value,' it gives specific examples (ticker or CIK). This helps the agent understand parameter usage even though the schema already documents them.

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 clear example queries and explicitly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific resources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes itself from the sibling 'entity_profile' tool.

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

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

The description provides explicit guidance on when to use this tool versus 'entity_profile' ('Use entity_profile instead when you want the static profile...'). It also gives typical usage examples and a recommended value for the 'since' parameter. It does not explicitly list exclusions, but the context is clear.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds key behavioral details: key-value pair storage, scoping by identifier, persistence differences between authenticated and anonymous sessions, and pairing with recall/forget. 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?

Four sentences, front-loaded with the primary action, no wasted words. Every sentence adds value: purpose, use case, mechanism, and context.

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

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

Given the simplicity of the tool (two simple string params, no output schema), the description covers all essential aspects: what it does, when to use, how it works (scope, persistence), and how it relates to siblings. No gaps.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context with example keys (subject_property, target_ticker, user_preference) and value types (findings, addresses, preferences, notes), enriching the schema definitions.

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

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

The description uses specific verbs ('Save', 'store') and resources ('data the agent will need to reuse later'), clearly distinguishing it from sibling tools like 'recall' and 'forget'. Examples of use cases (ticker, address, preference) further clarify the purpose.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and provides context about persistence differences. Although it doesn't explicitly list when not to use, the positive guidance is strong and alternatives (recall, forget) are mentioned.

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 (readOnly, openWorld, idempotent, non-destructive), the description discloses meaningful runtime behavior: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit labeling of unresolved identifiers under `unresolved` rather than silent omission, and source attribution for each identifier. It also notes that non-equity instruments without tickers still resolve, setting accurate expectations about coverage.

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

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

The description is information-dense and front-loaded with examples and the 'Use FIRST' directive, but the company-type section is a long, nested parenthetical with multiple em-dashes and semicolons that is hard to scan. Bullet points or shorter sentences would improve readability without losing content. Every sentence does contribute, but the structural compaction hurts 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?

With no output schema, the description fully compensates by listing exactly what is returned for each type: CIK, ticker, company_name, LEI with ownership hierarchy, FIGI, and RxCUI with ingredients and citation link. It also covers input variations, unsupported or edge cases, degradation behavior, and the fact that one call replaces several manual lookups. An agent has enough context to call and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds valuable semantic detail beyond the schema: accepted input forms (ticker, CIK, ISIN, company name; brand or generic drug name), concrete examples (AAPL, CH0038863350, ozempic), and the edge-case instruction to pass only the entity name, not the full noun phrase. It also clarifies that ISIN input maps to the legal entity via GLEIF, which is not obvious from the schema alone.

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

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

The description states a clear verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It is rich with concrete query examples (ticker, CIK, LEI, RxCUI) and explicitly scopes the tool as the identifier-resolution entry point. The supported types (company, drug) and their outputs are clearly delineated, distinguishing it from sibling tools that work with already-resolved entities.

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

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

The instruction 'Use FIRST whenever you have a name but need an ID' provides an explicit when-to-use rule and positions this tool ahead of others in the workflow. It also signals that other tools consume the identifiers resolved here. However, it does not name an alternative tool or state explicit cases where another tool would be preferred (e.g., when you already have an ID and need a profile), so it stops short of full exclusion guidance.

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

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

The description discloses key behaviors: it internally calls ai_visibility_check for each entity, ranks results, and outputs score, confidence, and signal density. Annotations already declare readOnlyHint, idempotentHint, etc., and the description adds valuable detail without contradiction. No behavioral surprises.

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

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

The description is three sentences long, each sentence adding value. The first sentence states the primary action, the second elaborates on mechanics, and the third provides a use case with an example. No redundant or vague phrasing.

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 the tool's purpose, internal workflow, output format (ranked list with metrics), and usage context. Given no output schema, it adequately explains return values. The complexity of comparing multiple entities is well addressed.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it specifies that the first entity is treated as the 'subject' for narrative purposes and constrains entities to 2-8 items. These details are not in the schema and help the agent understand parameter semantics.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This differentiates it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison). Verb 'compare' with specific resource 'AI visibility across entities' makes the purpose explicit.

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

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

The description includes a use case ('competitive AI-marketing audits') and an example question, providing clear context for when to use. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling list implicitly provides them. Still, the guidance is strong for a typical agent.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: fans out across deps.dev and bundlephobia, returns specific fields, handles partial failures gracefully, and mentions timing for first measurement. No contradictions with annotations.

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

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

The description is relatively long but efficient, packing many details without redundancy. It is front-loaded with the core purpose and provides structured information about return values and failure modes. Could be slightly more concise, but still well-organized.

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 annotations and schema, the description is very complete: it covers purpose, usage, behavior, parameters, output structure, limitations, failure modes, and ecosystem specificity. No output schema exists, but the description compensates by explaining the summary block and additional 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?

Both parameters are fully described in the schema (100% coverage). The description adds value by clarifying the default behavior for the 'version' parameter (defaults to latest) and that scoped packages are accepted, which goes slightly beyond the schema.

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

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

The description clearly states it is a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by specifying NPM ecosystem only in v1 and mentions alternative tools like deps.dev:version for other ecosystems.

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 to use when an agent asks about safety, popularity, or size of a package, or what adding a package costs. Provides context on limitations (NPM only, partial failures) but does not explicitly mention when not to use, though the usage is clear.

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

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

Annotations already indicate safe, idempotent, non-destructive read. Description adds model details (BGE-base-en, cosine, 500-char windows), character limit with truncation, and output structure with offsets. 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 with clear structure: purpose first, then usage, then technical details. No unnecessary words; every sentence adds value.

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

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

Despite no output schema, description fully explains return format (passages with offsets and similarity scores). Covers all important aspects: input, behavior, constraints, and output for a 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% so baseline 3. Description adds practical examples for query (e.g., 'supply-chain risk'), clarifies text max chars, and explains limit default. These enhance schema's descriptions.

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

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

Clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from sibling ask_pipeworx_grounded by describing how they pair together.

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

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

Explicitly tells when to use: 'when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. No alternatives needed beyond that.

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 scope (all of Title 17), input flexibility, and coverage areas, but does not detail response format or potential length constraints.

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

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

The description is dense but well-structured, with a clear lead sentence and logical grouping of examples and coverage. Slightly long but every sentence adds value; could benefit from bullet points for readability.

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

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

Covers input, scope, and disambiguation from related tools. Lacks output format details (plain text vs JSON), but given the tool's simple purpose, this is a minor gap. The description is sufficiently complete for an experienced agent.

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

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

Schema coverage is 100%, yet the description adds extensive value with numerous examples, common rule name mappings, and input format variations, greatly aiding correct parameter usage.

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

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

The description clearly states the tool retrieves the full text of an SEC regulation by citation or common name. It distinguishes itself from sibling tools like sec_regulations_search (search) and edgar/sec-xbrl packs (filings data), making its 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?

Explicitly says when to use (get exact regulatory wording) and provides forgiving input formats. It also mentions alternative tools for filings data, giving clear context for selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it is keyless, searches SEC rules text, and returns citations, headings, excerpts, and source URLs. 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?

Well-structured with purpose first, then examples, then return info. Slightly long due to topic list but no wasted sentences. Could be trimmed slightly but still effective.

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

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

Given no output schema, description adequately explains return values (citation, heading, excerpt, source URL). Examples further clarify usage. Complete for a search tool with full schema coverage.

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

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

Schema covers both parameters at 100%. Description reinforces with examples (e.g., 'insider trading') and clarifies limit range (1-20, default 10). Adds value over schema by showing usage patterns.

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 does keyword search across SEC regulations in 17 CFR, with specific examples of queries and topics. It distinguishes from siblings like edgar and sec-xbrl by stating it searches rules text, not filings.

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 example queries and topic areas where the tool is great, and notes that separate packs search filings data. However, it does not explicitly differentiate from the sibling tool `sec_regulation` or state when not to use it.

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

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

Discloses important behavioral traits beyond annotations: OAuth requirement, delivery constraints (phone verification, SMS cap, webhook signing secret returned once, auto-disable after 10 consecutive failures). No contradiction with annotations.

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

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

Dense but well-structured single paragraph. Front-loaded with purpose and return value, then requirements, types, and delivery. Could be slightly more concise but every sentence adds value.

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

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

Given complexity (multiple types, nested objects, no output schema), the description covers usage, constraints, and return value. Mentions return of subscription id and once-only webhook secret, which 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?

Adds significant meaning beyond the input schema: provides concrete examples for each type, details the params object structure, and explains delivery channel options comprehensively. Schema coverage is 100% but description enriches 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 clearly states the verb 'Create' and resource 'proactive monitoring subscription' with return 'Returns the new subscription id'. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Provides clear context: requires Pipeworx OAuth account, lists supported types and delivery channels with examples. However, does not explicitly state when not to use or compare to alternatives like recent_alerts.

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 readOnly, openWorld, idempotent, not destructive. Description adds that it returns example questions with tool shapes from a live catalog, and that it's the onboarding entry point.

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 front-loaded with alternative phrasings and then explains return structure and parameter usage. Could be more concise but remains effective with minimal waste.

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

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

Tool has 1 optional param and no output schema; description covers purpose, usage, return value, and parameter behavior completely for the intended onboarding use case.

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 adds context about the `topic` parameter's possible values and the effect of omitting it, effectively explaining the single parameter.

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

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

Description clearly states it's an onboarding entry point that returns categorized example questions with tool/argument shapes. Distinguishes itself from siblings by being the first tool to use when unsure.

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 to use FIRST when you don't know what Pipeworx can do, and provides guidance on calling with no arguments or with a topic. Does not contrast with specific siblings but implies 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 indicate non-destructive and idempotent; description adds valuable context: row is deactivated not deleted, historical events preserved. Transparently explains side effects beyond annotations.

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

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

Two clear, front-loaded sentences with no wasted words. Every sentence provides essential information.

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

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

For a simple one-parameter tool with no output schema, the description covers ownership, deactivation, and historical data persistence. No gaps for correct agent 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 has 100% coverage with description of 'id' param. The tool description mentions 'by id' but adds no extra semantic value beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by detailing ownership enforcement and deactivation behavior.

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

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

Provides clear context for when to use: canceling own subscriptions. Includes ownership enforcement and deactivation detail. Could explicitly mention not to use for others' subscriptions, but overall guidance 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already signal safe read-only behavior. The description adds substantial context beyond that: the dual-path routing (SEC EDGAR/XBRL vs grounded pipeline), the exact verdict set, and the critical distinction between could_not_verify (check did not happen, carries verification_error) and unsupported (no source covers it). This is rich behavioral disclosure that goes well beyond the annotations.

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

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

The description is front-loaded with purpose and example queries, then logically covers routing, return values, failure semantics, and efficiency. Every sentence contributes unique value—there is no filler or redundancy. Despite being longer than average, the complexity of the tool justifies the length, and it is well structured for skimming.

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?

Since there is no output schema, the description thoroughly explains the return structure: the enumerated verdicts, the grounded/structured value with pipeworx:// citation, and reasoning. It also covers important error semantics (could_not_verify vs unsupported) and the performance benefit of replacing multiple calls. This is sufficient for an agent to invoke the tool correctly and interpret results.

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

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

Both parameters (claim and tolerance_pct) have complete descriptions in the input schema (100% coverage), including examples, ranges, and defaults. The description itself does not add parameter-specific details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with specific example phrasings like 'Is it true that…' and 'fact check'. It explicitly states the resource (claims) and action (validate/verify), and differentiates itself from other tools by noting it replaces multiple sequential calls and has a dedicated SEC EDGAR/XBRL path for financial claims.

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

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

The description gives an explicit usage trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing for company-financial claims vs any other factual claim, which clarifies scope. However, it does not name alternative sibling tools or provide explicit when-not-to-use guidance, so it is not a 5.

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