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?

The annotations already indicate a safe read-only, idempotent operation. The description adds behavioral context beyond that: it routes to internal tools, fills arguments automatically, returns structured answers with stable citation URIs, and operates on every tier in one call. It does not fully describe failure/error behavior, but that is not a major gap for a read-only router.

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

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

The description is long but front-loaded, with the core prefer-over-web-search decision stated first and alternative tools at the end. Some repetition exists, but most sentences contribute either scope, examples, or routing guidance.

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

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

For a flexible, read-only question-routing tool with no output schema, the description gives enough to call it correctly: domain coverage, trigger phrases, examples, output style, and explicit escalation paths. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema documents the question parameter and its aliases. The description adds value by giving concrete example questions and specifying accepted natural-language question types, which helps an agent formulate the parameter value correctly.

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

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

The description states a specific verb and resource: it routes factual questions to the right of 5,724 tools and returns structured answers with citation URIs. It explicitly says it is the default entry point and contrasts with ask_pipeworx_grounded and deep_research, so an agent can distinguish it from sibling tools.

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

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

It names web search as the alternative to prefer over, gives trigger phrasings like 'what is' and 'look up', and explicitly says to step up to ask_pipeworx_grounded for hallucination-resistant single answers or deep_research for broad/multi-part questions. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already convey read-only, open-world, idempotent, and non-destructive; the description adds genuinely new behavioral context: candidate routing improvements are 'enabled live whenever one is under test', and currently 'No candidate is active right now' so it matches ask_pipeworx exactly. The explicit 'Falls back to nothing' explanation prevents the misconception that it is a fragile experimental wrapper.

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

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

The description is front-loaded with the beta identity and router function, followed by useful current state and usage guidance. It carries a specific retirement date and a slight redundancy between 'identical' and the enumeration of same tools/arguments/response shape, but each sentence contributes to a complete picture without major 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 no output schema, the description covers purpose, usage, current state, and dynamic behavior. Pointing to the 'same response shape' as ask_pipeworx lets an agent consult the sibling definition for return details. The main gap is that the actual response structure is not described here, but the reference to the stable sibling makes it reasonably 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 description coverage is 100%, and the schema already describes the question parameter and all five aliases clearly. The tool description adds nothing about parameter semantics beyond the generic statement 'same arguments', so it does not exceed the baseline established by 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 pins down the tool as 'Beta version of ask_pipeworx: identical universal router (same 5,724 tools, same arguments, same response shape)' and spotlights the only difference: candidate routing improvements when under test. It also explicitly calls it a 'full working router', removing any ambiguity that this is a beta stub. This clearly differentiates it from sibling ask_pipeworx and ask_pipeworx_grounded.

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

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

It gives a direct when-to-use instruction: 'Use it exactly like ask_pipeworx when you want the newest routing', and explains the experimental role by noting results are compared against the stable router. It does not explicitly name the stable alternative as the should-not-use tool, but the condition is unambiguous. It also preempts misuse with 'Falls back to nothing'.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial behavioral detail: returns a structured success object with verbatim evidence and confidence, or an explicit refusal with specific refusal_reason enum values. Also discloses the cost of one extra LLM call.

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

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

The description is dense but every sentence earns its place: it defines the mode, explains the mechanism, specifies return and refusal shapes, gives concrete use cases, and closes with a cost-based routing comparison. It is front-loaded and 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?

Despite having no output schema, the description fully documents the return payload and refusal reasons, making the tool's behavior predictable. It also explains the routing mechanism and clarifies the trade-off against ask_pipeworx, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the parameter descriptions fully explain that question is natural language and all other parameters are aliases. The tool description does not add significant parameter-level meaning beyond what the schema provides, so a 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?

States a specific purpose: a hallucination-resistant answer mode for high-stakes reads that routes like ask_pipeworx but extracts answers only from tool results. Clearly distinguishes itself from ask_pipeworx by emphasizing groundedness and refusal behavior.

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

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

Explicitly says when to use it: whenever an answer will be quoted, cited, or acted on and must not be invented. It also names the alternative ask_pipeworx and advises preferring it for casual lookups due to the extra LLM call cost.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing decomposition, parallel tool routing, findings packet structure, explicit gaps[], no invented answers, contradictions[], hop fields, citation_uri fetchability guarantees, semantic excerpting, timing expectations, and the paid requirement for thorough depth. No annotation contradiction is present.

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

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

The description is long but front-loaded with the critical account requirement and every sentence carries distinct information: alternatives, return payload, gaps behavior, citation semantics, excerpting, and latency. It is dense without being redundant.

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

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

With no output schema, the description fully compensates by specifying what the findings packet contains, how citations work, when gaps[] and contradictions[] appear, and how long the call takes. An agent has enough information to invoke the tool correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it ties 'thorough' to a paid plan, explains how depth levels change second-hop behavior, and clarifies that broad/multi-part questions are acceptable. It could go further by giving example questions, though the 'compare X and Y' example already helps.

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

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

States a specific verb, 'research,' and a clear resource: '1497 STRUCTURED data sources' in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell what deep_research does and does not do.

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 and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also names the best-fit scenario: 'broad/multi-part questions over structured data.'

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

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

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

Annotations already signal readOnly/idempotent/non-destructive, but the description goes far beyond them: it discloses that Kalshi fees are not modeled and spreads are gross, that unclassified legs are never paired, that temporal_alignment=null means 'could not be computed' rather than aligned, and that compatibility warnings may be non-empty even when matched_pairs>0. This is exceptionally transparent.

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

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

The description is long but densely packed and well-structured with labeled sections (MODE, RESPONSE, SAFETY FIELDS). It is front-loaded with the core purpose and mode selection. It loses a point because it repeats the full topic list already present in the schema and the safety-code catalogue becomes sprawling, even if each item earns its place.

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

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

Given there is no output schema, the description compensates thoroughly: it explains the response shape, the meaning of each safety code, the behavior of spread flags, skipped counters, fees disclosure, and temporal alignment semantics. An agent gets enough context to invoke the tool and interpret its result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining the two modes, that explicit params override the topic-mapped side, and that both modes share identical disclosure behavior. It also expands on the topic values with real-world guidance, though the schema already listed them.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly defines the tool's unique scope—comparing the same outcome across two venues—which distinguishes it from siblings like polymarket_arbitrage or polymarket_edges.

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

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

The description gives explicit mode guidance: use `topic` for 10 pre-mapped macros, or use explicit ticker/slug for custom pairings, and says both modes run the same matcher. It also warns that pre-mapped topics are not automatically tradeable. However, it never explicitly names alternative tools or states when to prefer them, so it stops short of full sibling routing.

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context beyond those hints: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns unresolved identifiers explicitly, and asserts nothing when multiple matches exist. This level of behavioral disclosure is unusually thorough.

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

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

The description is front-loaded with intuitive example queries and the 'Use FIRST' directive, and every major section serves a purpose. However, it is quite long and contains some dense parentheticals that could be tightened, such as the lengthy explanation of issuer-name ambiguity. It earns a high score for being structured and informative, but not perfect because the length risks burying key instructions.

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?

There is no output schema, so the description carries the full burden of explaining return values. It does this thoroughly: for companies it lists CIK, ticker, company_name, LEI, FIGI, ownership, and figi_candidates/unresolved fields; for drugs it lists RxCUI, ingredient, brand, and citation. It also covers edge cases like non-US issuers, non-equity instruments, and enrichment failures, making it complete for an agent to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes far beyond the schema. It clarifies what 'value' means for each type, gives concrete examples (AAPL, 0000320193, ozempic), and warns against including trailing security-class words for bond lookups. The type enum is also expanded with the exact lookup scope and resolution paths for company and drug.

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 and resources: resolve a user-spoken NAME to canonical/official identifiers, with explicit supported types (company and drug) and the exact identifiers returned (CIK, ticker, LEI, FIGI, RxCUI). It also differentiates itself by stating it should be used FIRST whenever a name is known but an ID is needed, distinguishing it from sibling tools like entity_profile and compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is a clear invocation condition. It also provides type-specific guidance, examples of accepted inputs, and caveats like passing the issuer name exactly instead of the full noun phrase for bonds. This gives an agent actionable direction on when and how to use the tool versus relying on other lookups.

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

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

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.