Digitalnz

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

Annotations indicate read-only, idempotent, non-destructive. Description adds: probes multiple LLMs, returns per-model and combined views, free default model, BYO key for Anthropic, no rate limits mentioned but consistent with readOnlyHint.

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

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

Concise single paragraph, front-loaded with core function. Every sentence adds value: usage, defaults, prerequisites, output summary. No waste.

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

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

Given 4 params (1 required) and no output schema, description fully explains return format (score, confidence, signals, raw_response per model + combined view) and motivation. 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 100%. Description adds examples (e.g., 'Pipeworx') explains default for models, clarifies _apiKey is only needed if 'anthropic' in models, and provides context for disambiguation. 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?

Describes probing LLMs for brand visibility with scoring (0-100) per model. Clearly distinguishes from siblings like ask_pipeworx or deep_research by focusing on AI-marketing audits and per-model scores.

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

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

Explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Mentions default model and prerequisite for Anthropic (_apiKey). No explicit exclusions or alternatives, 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?

Description adds rich behavioral context beyond the annotations: mentions routing to 5,529 tools across 1,455 sources, returns citation URIs, works on every tier, and is one fast call. Since annotations already declare read-only/idempotent, the description's additional details are valuable, though it doesn't mention edge cases like rate limits.

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

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

The description is longer than average but every sentence adds value: clear preference, examples, alternatives, and scope restrictions. It is dense and well-structured, though could be slightly tightened without losing meaning.

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

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

For a tool with a single question parameter and no output schema, the description provides comprehensive context: what to ask, what to expect (citations, structured answer), when to escalate to alternatives, and that it works across all subscription tiers. This is complete for agent selection.

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

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

The description supplements the schema by illustrating acceptable queries with examples ('current US unemployment rate', 'Apple's latest 10-K') and indicating trigger phrases like 'what is', 'look up', etc. The schema itself only says 'Your question or request in natural language', so the description adds semantic guidance.

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

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

The description clearly states the tool's function: it routes factual questions to a large set of sources, fills arguments, and returns structured answers with citations. It actively distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making the purpose unmistakable.

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

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

Provides explicit guidance on when to use this tool over alternatives: says 'PREFER OVER WEB SEARCH', lists categories of questions, gives trigger phrases, examples, and explicitly directs to alternatives like ask_pipeworx_grounded and deep_research for different needs. Also states it is the default entry point.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds important behavioral context: it's a full working router, falls back to nothing, and may currently match the stable version exactly. It discloses the experimental nature and that candidates may be enabled live. No contradiction with annotations; the only missing detail is the exact routing differences when a candidate is active.

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

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

The description is a single dense paragraph that front-loads the beta identity and key facts. It earns its length by explaining the relationship to stable, current state, and fallback behavior. Slightly verbose in the middle but every sentence adds useful context; no wasted words.

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

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

Given the tool is a beta twin of an existing sibling, the description covers the essential points: identical interface, experimental routing, current inactive state, and usage guidance. No output schema exists, but this is a router for natural language questions, so return format is less critical. The description is complete enough for an agent to use it safely and 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 description coverage is 100% with all six parameters described as aliases for 'question'. The description adds that the tool takes the same arguments as ask_pipeworx, reinforcing that all parameters alias the same natural-language question. This is a good baseline with schema carrying the load, and the description adds context about argument compatibility with the stable router.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling ask_pipeworx by noting it carries experimental routing improvements, though currently identical. The verb 'ask' and resource are clear, though it relies on comparison to sibling for full differentiation.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against stable router. This gives clear context on when to choose this over the stable sibling, though it doesn't explicitly name alternatives beyond the implied stable version. The guidance is sufficient for an agent deciding between ask_pipeworx and this beta.

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), the description discloses the exact return shape, including refusal reasons, the constraint that answers must come only from tool results, and the extra LLM call cost. This adds significant behavioral context without contradicting 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 structured with a lead summary, mechanism, return format, usage guidance, and cost tradeoff. Every sentence provides new information, making it dense yet readable. It is appropriately sized for 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 the simple schema and no output schema, the description fully compensates by explaining return formats, refusal behavior, and usage contexts. It covers purpose, mechanism, tradeoffs, and alternatives, making it complete.

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

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

The schema already covers 100% of parameters with descriptions, including aliases. The description adds no parameter-specific guidance beyond what the schema states, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function as a hallucination-resistant answer mode that extracts answers only from tool results, distinguishing it from the sibling ask_pipeworx by emphasizing groundedness. It highlights the specific use case for high-stakes reads and names the alternative. This is a specific verb+resource+behavior description.

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

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

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and explicitly prefers ask_pipeworx for casual lookups, stating the cost tradeoff. This effectively differentiates from alternatives.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral details: resolver contract (market_match_confidence, alternatives, suggestions), parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warnings), and resolution-rule 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 long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Front-loaded with main purpose. Every section provides necessary detail for a complex tool. Could be slightly more concise, but the length is justified.

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

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

Given the tool's complexity and lack of output schema, the description is exceptionally complete. It covers response shapes (market, analysis, evidence), resolver contract, parent event extractor, news fields, safety behaviors, and cancellation risk. No gaps are apparent for the intended use cases.

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

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

Schema coverage is 100% with all three parameters described. Description adds meaning: explains 'market' accepts slug, URL, or question text; 'depth' with enum values; 'include_raw' with recommended usage. Examples in schema provide context. The description adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet, simple market-vs-model comparison). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on data retrieval and analysis for a specific bet.

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 recommends use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Provides examples of fan-out for different bet types. Does not explicitly state when not to use, but the context is clear. Could mention alternatives for specific tasks like arbitrage.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds context: pulls latest 10-K data for companies (with off-calendar fiscal year handling) and FAERS/FDA/trials for drugs. Also mentions sorted results by primary metric. No contradictions with annotations.

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

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

Description is well-structured with front-loaded query examples. Every sentence contributes meaning, though slightly verbose. Could be trimmed by 10-15% without losing clarity.

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

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

Covers all key aspects: purpose, data sources, sorting, citation URIs, and efficiency claim. No output schema is present, but description provides sufficient behavioral detail for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, but description adds significant value: explains enum values (company vs drug) with what data each fetches, provides example inputs (tickers/CIKs for companies, drug names), and reiterates min/max 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 explicitly states the tool compares 2-5 entities side by side, with specific data for companies (10-K financials) and drugs (FAERS, FDA, trials). It distinguishes from sequential lookups and uses clear query patterns like 'X vs Y'.

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 prefer this tool over sequential lookups when comparing entities. However, it does not explicitly mention when not to use (e.g., for single entity lookup, where entity_profile would be appropriate), though the schema minItems=2 enforces this.

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 many behavioral traits beyond annotations: returns gaps[] for unanswered facets, never invents, includes contradictions[] for standard/thorough, ensures citations are always fetchable, uses semantic excerpting for large records, and provides expected timing. It does not contradict 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?

Although the description is long, every sentence adds unique value and it is well-structured: starting with account requirements, then core function, use cases, alternatives, depth behavior, output details, and timing. It is front-loaded with critical info and free of redundancy.

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

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

Given the tool's complexity and the absence of an output schema, the description is complete: it covers prerequisites, alternatives, the findings packet structure, gap handling, citation fetchability, contradiction detection, and expected latency. No important aspect is left unexplained.

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

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

Schema coverage is 100% and the schema already describes both parameters thoroughly. The description adds extra semantics, such as the meaning of depth levels ('standard re-angles unanswered gaps', 'thorough chases leads') and clarifies that broad questions are acceptable, adding 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 precisely states the tool's function: grounded multi-source research across 1,455 structured data sources, decomposing questions into facets and routing them in parallel to 5,529 tools. It clearly distinguishes itself from siblings like ask_pipeworx for single lookups and explicitly says 'this is NOT open-web search.'

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: 'Best for broad/multi-part questions over structured data' and contrasts with ask_pipeworx for single lookups and breaking news. It also specifies account requirements and that depth:'thorough' needs a paid plan, plus an alternative if not signed in.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: the tool returns schemas with curated examples ready to call, and accepts multiple aliases for 'query.' No contradictions.

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

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

The description is concise (5 sentences) with front-loaded purpose, usage guidance, and return format. 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?

No output schema, but the description explains return format (names, descriptions, schemas with examples). It covers key aspects for a discovery tool, though could mention if relevance scores are returned.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by explaining 'query' as a natural language description, providing examples, and stating aliases like 'task' and 'search.' This goes beyond schema definitions.

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

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

The description clearly defines the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and states it returns 'top-N most relevant tools with names, descriptions, and full input schemas.' This distinguishes it from sibling tools that perform other tasks.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It provides clear context for when to use, though it does not explicitly state when not to use or name 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing internal fan-out across sources, return fields, patent sunset (soft-fail), and URI 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?

The description is a single paragraph but is front-loaded with example queries and efficiently packs all necessary information. Slightly dense but concise for the content.

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

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

Despite no output schema, the description adequately explains all return fields (CIK, filings with URIs, fundamentals sorted, patents, news, LEI) and constraints (type restriction, patent status, name requirement). Complete for holistic profile tool.

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

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

Schema coverage is 100% and both parameters (type and value) are explained in the description. The description clarifies that value can be ticker or zero-padded CIK, and that names are not supported, going beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of US public companies, with example queries like 'Tell me about X' and lists specific outputs (CIK, filings, fundamentals, patents, news, LEI). It distinguishes itself from chaining individual 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 advises to prefer this tool over chaining single-pack lookups for holistic views. Also specifies that names are not supported and recommends using resolve_entity first if only a name is available.

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 confirms destructive nature, aligning with annotations (destructiveHint=true). Adds 'clear sensitive data' context. No contradiction with annotations; idempotentHint=true is consistent.

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

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

Two sentences, no wasted words, action verb first, 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?

Given single parameter and annotations, description adequately covers purpose. No output schema, but response format is not critical. Could mention idempotency or error handling, but not required for this simple tool.

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

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

Schema coverage is 100% with parameter 'key' described as 'Memory key to delete'. Description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying the verb (delete) and resource (memory by key). Distinguishes from siblings like remember and recall by focusing on deletion.

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 use cases: stale context, task completion, clearing sensitive data. Mentions pairing with remember and recall, but doesn't explicitly state when not to use or compare to alternatives beyond siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and emits standard llms.txt format, which is useful context beyond annotations. However, it does not mention potential rate limits or error handling for unreachable URLs.

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

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

The description is two sentences, front-loading the core action and output format, followed by concise use-case examples. Every sentence adds value with no redundancy or fluff.

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

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

Given the tool has 2 parameters, 100% schema coverage, and no output schema, the description sufficiently covers the output format ('standard llms.txt markdown format', 'single text blob') and its behavioral intent. No gaps are apparent.

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

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

Schema coverage is 100% with clear parameter descriptions for url and max_links. The description does not add additional semantic info about the parameters beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description explicitly states the tool generates a production-ready llms.txt file for a URL, with specific use cases like indexing a client's site or auditing a competitor. This clearly distinguishes it from sibling tools, none of which directly perform this function.

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

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

The description gives clear positive use cases (getting a client's site indexed, drafting for own project, auditing competitor) but does not explicitly mention when not to use the tool or suggest alternatives like scan_competitor_ai_presence or ai_visibility_check. This is adequate but lacks exclusions.

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

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

Annotations already declare readOnly and idempotent hints. The description adds the scope (caller's subscriptions) and returned fields, providing useful behavioral context beyond annotations.

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

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

Two efficient sentences: first states purpose and returned fields, second gives usage guidance. No wasted words.

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

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

For a simple list tool with strong annotations and full schema param coverage, the description is complete. It covers why and when to use it, and lists return fields.

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

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

Schema coverage is 100% with a clear description of the only parameter. The description does not add extra 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 clearly states the tool lists the caller's active subscriptions, specifies returned fields, and distinguishes from siblings like subscribe and unsubscribe.

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

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

The description provides explicit usage scenarios: review before adding more subscriptions or find an ID to cancel. While it doesn't list alternatives directly, 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?

Annotations only set all hints to false (no meaningful safety profile), so the description carries the burden. It reveals critical behaviors: anonymous filing yields a claim_token for later status retrieval, calls with only claim_token act as a read, the tool is rate-limited to 5/day per identifier, and it's free/quota-exempt. 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 information-dense, with each sentence adding either a condition, a constraint, or a behavioral detail. It's front-loaded with the core purpose and ends with cost/rate details. No fluff, though it could likely be trimmed without losing value; still earns its length.

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

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

The tool has no output schema, so the description must explain return behavior (claim_token, status later) and operational constraints (rate limits, quota, read-after-write). It also gives exclusion rules for non-Pipeworx tools. Given the complexity, this is a complete and self-sufficient description.

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

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

Schema covers 100% of parameters with descriptions, but the description supplements by explaining the claim_token round-trip flow (filing returns token; passing it back alone reads resolution status) and clarifying message content (describe in terms of Pipeworx tools, don't paste prompts). This adds meaning beyond the schema's per-field documentation.

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

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

The description opens with a clear verb+object ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately scopes it to Pipeworx connection tools, distinguishing it from sibling tools like ask_pipeworx or deep_research. It enumerates feedback categories (bug, feature, data_gap, praise), 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 explicitly states when to use (bug, feature/data_gap, praise) and when not to use (feedback about other vendors' MCP servers), and even instructs on what not to include (don't paste end-user prompt). It offers a concrete alternative ('file it with that server instead'), going beyond typical guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds essential details: self-aggregating signal derived from CF analytics-engine, no PII, data format (pack, tool, count), and caching duration (5min-1h depending on window). No contradictions.

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

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

The description is concise: three sentences plus a parenthetical list. It opens with the core functionality, then lists use cases, and ends with technical details. Every sentence adds unique value; no redundancy or fluff.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description fully informs the agent: what it returns (top tools, packs, volume), data source, privacy, and caching. The agent can confidently decide to invoke this tool without ambiguity.

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

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

The only parameter 'window' has an enum description in the schema. The description adds meaningful context beyond schema: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose the appropriate window for its goal.

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

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

The description clearly states what the tool does: returns trending data on tool and pack usage from other AI agents, including top tools, top packs, and total call volume over selectable windows. It distinguishes itself from sibling tools like discover_tools by focusing on trending behavior rather than general discovery.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming a popular tool as canonical, and aligning use cases with current demand. It also explains the window parameter's effect (shorter for hot trends, longer for steady-state), providing clear guidance on when to use each.

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 readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: it performs Jaccard similarity filtering (≥0.30), partition filter (placeholder slugs), fill check against CLOB depth, and explains when signals are not tradeable. 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 long and contains extensive technical details (e.g., Jaccard threshold, partition filter logic, fill check mechanics). While informative, it could be more concise for quick agent parsing. However, it is front-loaded with purpose and modes, which helps.

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

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

Given no output schema, the description fully explains the response structure: opportunities array with gap_pp, suggested_trade, reasoning, and for event mode partition_check details. It also covers edge cases like placeholder filtering, fill check, and cross-event similarity. Complete for agent invocation.

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

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

Both 'event' and 'topic' parameters are fully described in the schema (100% coverage). The description enriches them with usage context: event accepts slugs or full URLs, topic accepts seed questions. It clarifies the difference between the two and recommends event mode for specific markets.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from siblings like polymarket_edges by specifying the unique methodology and offering three distinct modes (trending_scan, event, topic).

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

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

Provides explicit guidance on when to use each mode: no args for trending_scan, event for specific market (recommended), topic for cross-event scanning. It explains cross-event catches patterns that single-event misses, and refers to polymarket_fill_risk for custom sizing. Comprehensively covers when to use and when not to.

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

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

Annotations already mark this as read-only, idempotent, non-destructive. The description goes far beyond by detailing caching (1h KV-level), formula details (lognormal barrier, GDELT ratios, partition_overround α values), placeholder filters, Fed data limitations, and diagnostics. This rich context adds immense value beyond structured fields.

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 thorough but extremely long (several paragraphs). While every sentence provides detail, it sacrifices brevity. Front-loads purpose, but the depth of technical explanation may overwhelm quick scanning. It earns a 3 as adequate but not 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?

Despite missing output schema, the description comprehensively explains the response structure (by_segment segments, diagnostics), caching behavior, edge cases (Fed note, placeholder filters), and all knobs. With 9 parameters and complex logic, this description fully equips an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with good descriptions. The description adds additional operational context, e.g., explaining why min_kelly doesn't filter partitions and how min_partition_leg_kelly works instead. This adds value beyond the schema, justifying a score above the baseline 3.

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

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

The description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies three model families and segments, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explicitly says 'Built for what should I bet on today' and explains knobs for filtering (min_liquidity, max_spread_pp). However, it does not explicitly state when NOT to use this tool vs alternatives, though the highly specific context implies its use case.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral context: the tool reads snapshots (safe operation), data depends on snapshot availability (open-world), and decay is computed from daily closes, not intraday. No contradictions; the description enhances transparency.

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

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

The description is thorough but not overly verbose. It front-loads the core purpose and then details the response structure. While it is long, every sentence contributes value. Minor improvement could be separating the response structure more concisely, but overall it is well-structured.

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

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

The description fully explains the response: tracked opportunities with time-series and trends, expired opportunities with lifespan, and snapshot dates. It also covers limitations (TTL, data gaps, decay computation). Without an output schema, this description provides complete contextual understanding for an agent.

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

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

Schema description coverage is 100% and includes defaults and constraints. The description restates these (days: default 14, max 30; window: default '1wk') without adding significant new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge duration and shrinkage, differentiating it from sibling tool 'polymarket_edges' which likely provides raw edge data without historical context.

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 explains when to use the tool: to understand if an edge is shrinking or has persisted for weeks. It implies a trade-off between fresh wide edges and older ones. However, it does not explicitly mention alternative tools or when not to use it, though the context is clear from the sibling list.

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=false. The description adds behavioral details: walks the ladder, returns verdict, warns about forced directional risk and thin legs. 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 well-structured with bold headings (SINGLE-MARKET, BASKET). Every sentence provides critical guidance. Slightly verbose but justified by complexity.

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

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

No output schema exists, but the description fully enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers edge cases like thin legs and forced directional risk.

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 context: default values, size interpretation (max spend vs target proceeds), basket auto side logic, and clamp range. This adds significant value beyond the schema.

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

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

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly references sibling tools to differentiate usage.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why partial basket fills create directional risk. It also clarifies when to use each mode.

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

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

The description provides extensive behavioral context beyond annotations, including explanations of compatibility_warning conditions, temporal alignment, skipped cross types, and the meaning of various response fields. Annotations already indicate idempotent and read-only behavior, and the description adds rich detail without contradiction.

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

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

The description is dense and front-loaded with the main purpose. While lengthy, every sentence provides essential details for correct usage. It could be slightly more concise, but the trade-off for completeness is justified.

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

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

Given the complexity of the tool (cross-venue spread, multiple edge cases), the description covers all necessary aspects: modes, safety fields, temporal alignment, and interpretation of warnings. No output schema exists, so the description adequately explains return values.

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

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

Schema coverage is 100% with descriptions for each parameter, but the description adds significant value by explaining the two modes and how parameters interact (e.g., explicit overrides). It clarifies the use of 'topic' as a shortcut and provides examples in the schema.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison and provides specific details about the two modes of operation.

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

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

The description explains when to use each mode (topic vs explicit) and warns that most pre-mapped topics return compatibility_warning, advising against assuming tradeability. It does not explicitly list alternative tools, but the context of sibling tools provides implicit guidance.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). Description adds listing behavior and scope identifier, enhancing transparency 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?

Three concise sentences, front-loaded with core functionality, no redundant information.

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

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

Given simple tool (1 optional param, no output schema), description fully explains behavior, scope, and pairing with siblings, sufficient for agent 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 already describes parameter 'key' and listing behavior. Description adds concrete examples of memory contents (ticker, address, notes), providing 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 uses specific verbs ('retrieve', 'list') and resource ('value saved via remember', 'all saved keys'), clearly differentiating 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?

Provides context on when to use (look up context like ticker, address, research notes) and scope (scoped to identifier). Lacks explicit 'when not to use' but is clear given sibling pairs.

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 details on returned fields (source, citation_uri, raw payload) and the mark_read flag's effect on subsequent calls, providing useful behavioral context beyond annotations.

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

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

The description is a single paragraph of about 4 sentences, front-loaded with the main purpose. It is efficient but could be slightly more structured (e.g., bullet points for parameters).

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

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

Despite no output schema, the description explains return fields and alternative access. It covers all parameters, use cases (polls, filtering), and behavioral nuances (mark_read). The tool complexity is low, and the description fully addresses its 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?

With 100% schema coverage, description adds significant meaning: clarifies type filtering with an example ('sec_8k'), explains since as ISO timestamp, and describes mark_read/unread_only behavior in plain language, exceeding the schema's minimal 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 starts with 'Pull fired events from your subscription feed,' a clear verb+resource. It mentions specific filters (type, since) and distinguishes itself from sibling tools like search or subscription management by focusing on 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?

The description explains when to use it (to get recent alerts) and mentions polling works fine, with an alternative REST endpoint for scripts/dashboards. However, it does not explicitly state when not to use it or compare to siblings.

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

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

The description adds significant behavioral context beyond annotations: it fans out to multiple sources, explains fallback order (GDELT→GNews on rate limit), notes USPTO API sunset, and specifies return structure (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

The description is a single paragraph that front-loads purpose with example queries, then covers sources, parameters, return format, and sibling guidance efficiently. Every sentence adds value, with no redundancy.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail, parameter formatting), the description covers all necessary aspects: parallel call, data sources, parameter details, return structure, and citation URIs. It is fully complete.

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

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

Although schema coverage is 100%, the description adds meaning by explaining accepted formats for `since` (ISO date or relative shorthand with examples) and clarifying `value` accepts ticker or CIK. It also restrains `type` to only "company".

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

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

The description starts with explicit user queries ("What's new with X") and clearly defines the tool as a change feed for a company in a time window, listing data sources. It distinguishes from the sibling entity_profile, making the purpose unambiguous.

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

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

The description provides clear when-to-use guidance (recent changes queries) and explicitly advises against using it for static profiles (use entity_profile instead). It also offers parameter tips ("Use '30d' or '1m' for typical monitoring").

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not need to repeat safety. The description adds that the tool fetches 'full details' and uses a specific id, which is consistent with annotations and provides additional 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 a single sentence with no wasted words, front-loaded with the verb 'Fetch', and every phrase is meaningful.

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 simple nature of fetching one record and rich annotations, the description is largely complete. It explains what the tool does, what input is needed, and how to get the id. The lack of output schema is not a major issue as 'full details' is a common expectation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that the 'id' parameter comes from the 'id' field of search results, which helps the agent understand the parameter's origin beyond the schema description.

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

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

The description states the specific verb 'Fetch' and resource 'full details for one DigitalNZ item by id', clearly distinguishing from sibling tools like 'search' which return lists.

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 implicitly guides usage by specifying the input is a DigitalNZ record id from the 'id' field of search results, indicating when to use after a search. No explicit alternatives or exclusions are given, 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?

Adds context beyond annotations: 'scoped by your identifier', 'persistent memory for authenticated users', '24-hour retention for anonymous sessions'. Transparent about scoping and persistence.

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 no fluff. First sentence states core purpose, second provides usage context and sibling references. Well-structured and front-loaded.

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

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

Fully sufficient for a simple 2-parameter tool. Annotations cover read/write/destructive hints, and description covers scoping and retention. No output schema needed; nothing missing.

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

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

Schema coverage is 100% (all parameters described). Description adds only examples of keys ('subject_property', 'target_ticker'), which provides marginal extra context. 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?

Clearly states 'Save data the agent will need to reuse later' and specifies the action (save) and resource (key-value pairs). Distinguishes from sibling tools 'recall' and 'forget'.

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

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

Provides explicit when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget. Lacks explicit when-not scenarios, but the usage context is well defined.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond these: it details cross-source identity spine, graceful degradation of LEI/FIGI enrichment, explicit 'unresolved' reporting, and cascading internal lookups. This far exceeds the baseline.

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

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

The description is long and detailed, but it is well-structured: front-loaded with usage examples and core statement, then supported type breakdowns, then enrichment details. Every sentence provides relevant information, though some redundancy (e.g., repeating 'accepts brand or generic name' within the drug section) keeps it from a perfect 5.

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

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

For a tool with no output schema and only 2 simple params, the description is remarkably complete. It covers what identifiers are returned, source attribution, handling of unresolved identifiers, graceful degradation, and even cites the internal multi-step lookup. There is no ambiguity left about expected behavior or output.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantic detail: for 'company' it lists acceptable input formats (ticker, CIK, name) with examples, and for 'drug' specifies brand/generic names. It also explains what each parameter corresponds to in output, going beyond the schema's brief enum and value descriptions.

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

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

The description states the tool's purpose with a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), and explicitly distinguishes itself from siblings with 'Use FIRST whenever you have a name but need an ID.' It also enumerates example queries and outputs.

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

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

Provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also contrasts with manual lookups ('replaces 2-3 manual lookups') and gives per-type input options, making the when-to-use crystal clear without needing to reference alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. Description adds behavioral detail: probes each entity with ai_visibility_check, ranks by score, returns score/confidence/signal density. 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 well-structured sentences plus a clarifying example query. Front-loaded with core action, no redundant words, efficient and informative.

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

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

Given no output schema, the description adequately explains return values (ranked list with score, confidence, signal density). Covers key aspects: how it works (probes with ai_visibility_check) and what it produces. Slight gap: no mention of error handling or rate limits.

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

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

Schema coverage is 100%, so parameters are documented. Description adds value by noting that the first entity is treated as 'subject for narrative,' which is not in the schema. Also clarifies default models behavior.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb 'compare' and resource 'AI visibility,' and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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 use case: 'Useful for competitive AI-marketing audits.' Implicitly suggests when to avoid by indicating single-entity probe via ai_visibility_check, but lacks explicit 'when not to use' or alternative names.

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. The description adds behavioral context: fans out across two services, returns summary block with specific fields, handles partial failures gracefully with sources_failed. This goes well beyond the annotations.

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

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

The description is relatively long but every sentence adds value. It front-loads the main purpose, then details return format and edge cases. Could be slightly more concise, but the level of detail is justified given the tool's complexity.

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

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

Given the tool's complexity (composite, multiple services, partial failures), the description is thorough. It covers return format, ecosystem limitation, edge cases (scoped packages, default version), and timeout behavior. No output schema, but description compensates well.

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

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

Schema coverage is 100% with clear descriptions. The description reiterates that version defaults to latest and scoped packages are accepted, but does not add significant new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, covering license, advisories, version history, and bundle size from two services. It distinguishes itself from siblings by being a single call that aggregates multiple checks, and specifies it's for npm only in v1.

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 (e.g., questions about safety, popularity, size, cost) and provides guidance for other ecosystems (use deps.dev:version directly). Also notes partial failure behavior and timeout, giving clear expectations.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by specifying returned fields (ids, titles, creators/sources, dates, links) and pagination behavior, without contradicting 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 concise sentences, front-loaded with purpose, no redundant information. Every word is meaningful.

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 read-only search tool with good annotations and schema, the description adequately explains return fields and pagination. It could mention error handling or result count limits, but overall it's complete enough.

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

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

The input schema covers all 4 parameters with descriptions, achieving 100% coverage. The description adds context about return structure (fields) and hints at integration with the 'record' tool ('pass an id to record'), which helps usage 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 states 'Search the DigitalNZ collection by keyword' with a specific verb and resource, and it distinguishes from sibling tools like 'search_within' by implying a top-level search 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?

It clearly implies use for keyword search but does not explicitly state when not to use it or mention alternatives among siblings like 'search_within' or other search-related tools.

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

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

The description adds substantial behavioral context beyond annotations: it details the return format (top-N passages with offsets and similarity scores), the embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and input limits (200K chars with truncation flagging).

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

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

The description is concise yet comprehensive. Each sentence serves a purpose: purpose, usage scenario, return details, pairing, technical specifics. 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?

Despite lacking an output schema, the description fully explains return values (passages with offsets and similarity scores), input constraints (200K chars), and pairing context. Given sibling tools are listed, the description clearly differentiates this tool's role.

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 enriches understanding by explaining the purpose of 'text' (document to search) and 'query' (natural-language query with examples), and specifies the 'limit' range and default. This adds value beyond the schema's bare descriptions.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It clearly distinguishes from siblings by mentioning pairing with 'ask_pipeworx_grounded' and targeting records too large for prompts.

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: use when the record is too big to cram into the prompt. It mentions pairing with ask_pipeworx_grounded and gives examples of queries. However, it does not explicitly state when not to use it or list alternatives beyond the paired 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 idempotentHint=true and readOnlyHint=false; description adds that persistence requires OAuth, SMS has a 10/day cap, webhook auto-disables after 10 failures, and returns subscription ID. 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 fairly long but well-structured. Every sentence adds value, covering purpose, requirements, types, and delivery options. Could be slightly more concise but justified by complexity.

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

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

The description covers prerequisites, 5 subscription types with detailed params, multiple delivery channels with constraints, and return value. For a tool with no output schema, this is very complete.

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

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

Schema coverage is 100%; the description enriches each parameter with concrete examples (e.g., sec_8k items codes, polymarket_edge topics) and delivery constraints. Greatly aids understanding beyond the bare schema.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream, lists supported types, and distinguishes from siblings like 'unsubscribe' and 'list_subscriptions'.

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

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

The description explains when to use it (subscribe to specific event types) and prerequisites (OAuth account, phone verification for SMS). It could be more explicit about when not to use alternatives, but the context from sibling names provides guidance.

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

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

Annotations already indicate read-only and idempotent. Description adds that it returns category-bucketed example questions with tool+argument shapes, providing full behavioral context beyond annotations.

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

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

Description is thorough but slightly verbose. However, it is front-loaded with key phrases and each sentence adds value.

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

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

Given single optional parameter, no output schema, and full annotations, the description completely explains when and how to use the tool, including return structure and use cases.

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

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

Schema coverage is 100% with the optional topic parameter. Description adds examples but not substantive new meaning beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point for suggesting questions about Pipeworx. It lists verb phrases like 'what can I ask Pipeworx?' and distinguishes from sibling tools like ask_pipeworx which answer questions.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Gives 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 show idempotentHint=true and destructiveHint=false; description adds that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This goes beyond annotations and clarifies side effects.

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

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

Two concise sentences with no fluff; the purpose is front-loaded. 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?

With one parameter, no output schema, and good annotations, the description provides ownership rules and deactivation behavior, fully covering what an agent needs to use the tool correctly.

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

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

Schema covers the single id parameter 100%, with description 'Subscription id (uuid) returned by subscribe.' The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description starts with 'Cancel a subscription by id,' clearly specifying the action and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by indicating it is the cancellation counterpart.

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?

States 'Ownership is enforced — you can only cancel your own subscriptions,' providing an important constraint. While it doesn't explicitly contrast with other tools, the context implies usage after subscribing.

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

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

Even with annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral context: it explains the automated routing (fast path for SEC financials vs. grounded pipeline), defines each verdict meaning, crucially warns that 'could_not_verify' means the check did not happen and must not be treated as evidence, and clarifies the 'unsupported' semantic. It also reveals the internal error structure (verification_error with stage/detail), which is not inferable from annotations.

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

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

The description is dense but each section earns its place: trigger phrases, use cases, pipeline differentiation, verdict semantics, caveats, and efficiency gains. It is somewhat long, but the complexity of the tool justifies the length. Front-loaded with example phrases makes it immediately scannable. A slight redundancy exists between the phrase list and the rest, but it does not detract significantly.

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

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

This is a complex tool with two execution paths, multiple possible verdicts, and important error semantics, yet no output schema. The description covers all of these: what inputs are expected, how each claim type is processed, what return values look like (verdict, value, citation, reasoning), and the crucial distinction between 'could_not_verify', 'unsupported', and 'refuted'. It is complete enough for an agent to select and invoke the tool correctly without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful nuance beyond the schema: it explains that 'tolerance_pct' overrides the claim's implied tolerance, gives a practical range (1-2) for hallucination detection, and states the default behavior (implied by wording, capped at 5). It also provides example claims for the 'claim' parameter, reinforcing the natural-language format.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with specific verb ('verify') and resource (factual claims). It distinguishes itself by detailing two distinct pipelines (SEC EDGAR structured path and grounded fallback) and explicitly lists the output verdict types, making it unmistakable what the tool does. This is significantly more specific than a generic 'validates claims' statement.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides conditional guidance based on claim type (company-financial vs. other) and notes that it replaces 4-6 sequential calls, implying you should use this tool rather than orchestrating multiple steps. However, it does not explicitly name alternative tools or state when *not* to use it, missing a full exclusion clause.

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