Nypl

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

Annotations already declare readOnly/Open World/idempotent/non-destructive, and the description supplements this with key behavioral details: default model and cost implications, per-model return structure (score, confidence, signals, raw_response), and that _apiKey is passed through to Anthropic directly. 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?

Four densely informative sentences with zero filler. Every sentence contributes unique value: what it does, default model and pricing, return format, and use cases. Properly front-loaded with the core purpose first.

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 parameters (1 required), no output schema, and moderate complexity, the description fully covers return shape, model options, key handling, and intended scenarios. There are no obvious gaps in what an agent needs to decide whether and how to invoke this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: explains that _apiKey is only needed for anthropic model and that you pay Anthropic directly, that context helps disambiguate common names, and that models can be omitted for default behavior. This elevates it above baseline.

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

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

The description states a specific action ('Probe one or more LLMs') with a clear resource (business/brand/product/topic) and measurable outcome (visibility score 0-100 per model). It clearly distinguishes from siblings like scan_competitor_ai_presence by focusing on LLM knowledge scoring rather than marketing presence scanning.

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

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

Provides clear context on when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains model selection (default free Workers AI vs BYO Anthropic key). It doesn't explicitly name alternative tools to use instead, but the use-case guidance is sufficient for most agents.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds meaningful context about routing logic, argument filling, citation URIs, and 'one fast call' performance. It does not disclose potential rate limits or error modes, but with strong annotations this is acceptable.

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 most important directive ('PREFER OVER WEB SEARCH') and followed by concrete examples. Some redundancy exists in the list of triggers and examples, but the length is justified given its role as a default entry point with many alternative tools to disambiguate.

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 meta-router tool with no output schema, the description covers the core behavior, use cases, alternatives, examples, and return format (structured answer with citation URIs). It fully equips an agent to decide when and how to invoke it, and what to expect back.

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

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

Schema coverage is 100% and all six parameters are aliases for the same 'question' field, clearly described in the schema. The description adds no parameter-specific detail, but the schema fully documents the input, making the baseline 3 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: route questions to the right specialized tool across 5,521 sources and return a structured answer with citation URIs. It distinguishes itself from siblings by naming alternatives (ask_pipeworx_grounded, deep_research) and positioning itself as the default entry point.

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

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

Explicit guidance is provided: 'PREFER OVER WEB SEARCH' for factual/real-world data, 'START HERE for most questions', and 'Step up only when needed' with specific alternatives for stronger grounding or broader fan-out. Also covers breaking-news use case and confirms it works on every tier.

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

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

The description discloses that behavior may change dynamically ('candidate routing improvements enabled live whenever one is under test') and that currently no candidate is active, matching ask_pipeworx exactly. This adds crucial context beyond annotations about mutability and experimental status, with 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 informative and well-structured, front-loading the beta status and key details. It is slightly redundant ('identical universal router' and 'currently matches ask_pipeworx exactly' overlap), but every sentence carries meaningful context about experimental status and usage.

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 router tool with no output schema, the description covers its purpose, relationship to the stable version, current state, and when to use it. It lacks explicit details about response format beyond 'same response shape,' but this is sufficient given the consistency with ask_pipeworx and strong annotations.

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

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

The input schema already covers all 6 parameters with clear alias descriptions, so schema coverage is 100%. The description only says 'same arguments' which adds no new parameter-specific meaning, but it does confirm consistency with ask_pipeworx. 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 identifies this as a beta version of ask_pipeworx, an identical universal router with 5,521 tools and same arguments/response shape. It distinguishes from the stable sibling by highlighting candidate routing improvements, making its specific role 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?

Explicit guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing' and 'results are compared against the stable router to decide what merges.' This tells the agent when to choose this tool over the stable alternatives, and clarifies it is a full working router, not a fallback.

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

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

The description reveals critical behavioral traits beyond annotations: it makes an extra LLM call, returns a structured response with evidence (verbatim quote) and confidence, and may return explicit refusal reasons ('not_in_source', 'no_tool_match', etc.) when data doesn't directly answer. This adds context that annotations (readOnlyHint, idempotentHint) do not convey, such as the refusal behavior and cost implication.

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

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

The description is dense and information-rich, but longer than strictly necessary. Each sentence serves a purpose—purpose, mechanism, return format, usage, cost—so it's well-structured. However, the return format details could be seen as slightly over-specified, but given the tool's high-stakes context, it justifies its length. Slightly less concise than the two-sentence ideal, but no wasted words.

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

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

Given the tool's complexity (an answer mode with refusal logic, extra LLM call, multiple use cases), the description is remarkably complete. It covers purpose, differentiation from sibling, behavior, output schema (though no formal output schema exists), usage guidelines, and cost trade-off. The agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100%, with each parameter (q, text, input, query, prompt) explicitly documented as an alias for 'question.' The description adds no additional parameter-level meaning, but since the schema fully covers semantics, the baseline of 3 is appropriate. The description's mention of 'picks the right tool... fills arguments' is process context, not parameter-specific detail.

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, high-value purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It then clearly differentiates from the sibling ask_pipeworx by stating it 'EXTRACTS the answer using ONLY what the tool result contains,' making the read-only, grounded nature explicit. The verb-resource pairing ('extracts the answer') is direct and 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 explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also names the alternative ('ask_pipeworx') and gives a clear exclusion: 'prefer ask_pipeworx for casual lookups.' This is exemplary usage differentiation.

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 is exceptionally transparent, covering resolver confidence and alternatives, safety short-circuiting ('status:"low_confidence_match"'), wide-spread illiquidity, cancellation-rule parsing, and news fallback behaviors. These details go far beyond the generic annotations (readOnly, openWorld, idempotent) and provide crucial operational semantics for an agent.

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

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

The description is long but well-organized with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and a front-loaded purpose. It is dense with unique information, but a few asides (e.g., the de-indexing explanation) could be trimmed. Overall it is well-structured despite 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?

With no output schema, the description fully covers return shapes (result.market, result.analysis, result.evidence), resolver contract, parent-event extractor, news fields, and safety statuses. It also instructs agents to inspect resolver fields before trusting the analysis and handles edge cases like closed markets and wide spreads, making it complete for a complex 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?

The input schema already documents all three parameters (market, depth, include_raw) with 100% coverage. The description restates the market input forms but adds no new parameter-level meaning; fan-out examples describe tool behavior rather than parameter semantics. Thus 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the tool's role (evidence packet + market-vs-model comparison) and distinguishes it from siblings like ask_pipeworx or deep_research through its unique classification and fan-out 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?

Explicit use cases are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context for when to invoke the tool. However, it does not explicitly state when NOT to use it or name alternative tools, stopping short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint, etc., so the description adds context beyond them: it explains SEC EDGAR/XBRL data source, off-calendar fiscal year handling, and result sorting. This enriches the behavioral understanding without contradicting any annotation.

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

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

The description is dense but well-organized, starting with user phrasing, then purpose, usage preference, and type-specific details. While longer than ideal, each sentence adds critical behavior or context, and the structured flow aids comprehension.

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 adequately explains the return value (paired data + citation URIs) and covers data sources, sorting, and type-specific metrics. It gives a complete picture for the tool's simple parameter set.

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

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

The input schema already covers both parameters with descriptions, so the baseline is 3. The description adds significant value by explaining what each type pulls (e.g., 10-K metrics for company, FAERS counts for drug) and giving concrete examples for values, 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 performs side-by-side comparison of 2-5 companies or drugs in a single call, distinguishing it from sequential lookups. It uses specific verbs like 'compare' and 'rank' and cites concrete query examples, 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 says to 'ALWAYS PREFER' this tool over sequential single-pack lookups when comparing entities, and provides clear examples of when to use it (X vs Y, which is bigger, rank these). This gives strong guidance on when to invoke it instead of alternatives like entity_profile.

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

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

The description adds extensive context beyond annotations: account/paid-tier requirements, expected latency (15-60s, up to ~90s), explicit 'this is NOT open-web search', the guarantee that gaps[] are 'never invented', details about resolvable citation_uri, contradictions[] scanning, semantic excerpting, and the hop field. With annotations already declaring read-only and idempotent, this additional context fully characterizes behavior.

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 critical account/alternative info and every sentence contributes meaningful detail. It is somewhat sprawling as a single paragraph, but the density of useful behavioral facts justifies the length. Not zero-waste, but close.

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

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

For a tool with only 2 parameters, no output schema, and rich annotations, the description fully covers what an agent needs: return format (findings packet with evidence, confidence, source, fetched_at, citation), limitations, latency, alternatives, and edge cases (empty gaps for non-structured topics). It leaves no critical gap.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds the critical prerequisite that depth:'thorough' requires a paid plan, and clarifies depth semantics like 'second-hop iteration' and gap recovery, which are partially redundant with the schema but still valuable for decision-making.

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: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,521 tools IN PARALLEL.' It uses a specific verb+resource+scope and explicitly contrasts itself with open-web search and sibling tools like ask_pipeworx, making differentiation clear.

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: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also gives an alternative for unsigned users: 'If you are not signed in, use ask_pipeworx instead.' This is a model of usage 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 mark it as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it returns top-N tools with full schemas and examples, and each result is 'ready to call directly, no second schema lookup needed.' This explains the return behavior beyond what annotations cover.

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 bit longer than minimal but every sentence carries weight: main purpose, use case list, return value, and strategic advice. The domain list is useful for prompting but could arguably be shorter. It is front-loaded with the core function, so structure is effective.

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

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

For a discovery tool with no output schema, the description fully covers what it does, when to use it, what it returns (top-N with full schemas), and how to invoke it efficiently. It even notes that no second schema lookup is needed, addressing a common user concern. The coverage is 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%, with each parameter including aliases and a natural language description. The tool description adds value by providing a broad list of example domains (e.g., FDA drugs, FRED economic data, ATTOM real estate) and stating that queries can be task descriptions like 'analyze housing market trends,' which enriches the user's understanding of query formulation 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 'Find tools by describing the data or task' with a specific verb and resource, and it lists concrete domains (SEC filings, financials, FDA drugs, etc.). It distinguishes itself from siblings by being a meta-tool for discovering other tools, especially given the sibling names like search, search_within, and item.

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

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

Provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates when to use it over directly invoking a known 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses important behavioral traits: it fans out across multiple sources, returns a structured payload with URIs, and notes that the patents API will sunset May 2025 and will 'soft-fail until reactivated.' Also reveals the GDELT→GNews fallback chain. No contradiction with annotations.

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

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

The description is dense but every sentence adds value: trigger phrases, core purpose, usage preference, output breakdown, API caveats, and input restrictions. It is well-structured and front-loaded with organic language examples, then systematic return fields, and ends with input disambiguation. No filler.

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

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

Given there is no output schema, the description thoroughly explains the return payload: cik, company_name, recent_filings with pipeworx URIs, fundamentals (specific fields), patents, news fallback, and LEI. It also covers the parallel-call nature, the unsupported name input, and the resolve_entity prerequisite. This is a complete picture for an agent to select and invoke the tool.

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

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

Schema coverage is 100% with both parameters already well-described. The description's param-related text ('Pass ticker AAPL or zero-padded CIK 0000320193') mirrors the schema descriptions without adding new semantics. It does add real-world example context but doesn't exceed what the schema already provides; 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 opens with explicit user-intent examples ("Tell me about X", "company profile for Microsoft") and a direct statement: "full cross-source profile of a US public company in ONE parallel call." It clearly distinguishes itself from sibling tools by stating it should be preferred over chaining single-pack SEC/XBRL/news lookups and by referencing resolve_entity for name-only queries.

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

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

Provides explicit when-to-use guidance: use when the user asks for a holistic view ('ALWAYS PREFER over chaining single-pack lookups'). It also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name)', directly naming the alternative sibling 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?

The description confirms the destructive nature but relies heavily on annotations (destructiveHint=true, readOnlyHint=false) for the safety profile. It adds usage context but no additional behavioral details like error handling or return behavior. With annotations covering the key trait, this is adequate but not rich.

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: the first states the action, the second provides usage guidance and sibling references. No fluff or redundancy, front-loaded with the core purpose.

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

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

For a simple one-parameter tool with no output schema, the description is complete enough. It covers purpose, usage, and pairs with related tools. It could mention idempotent behavior if key is missing, but the annotations already handle that, so the description suffices.

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

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

The input schema already provides 100% coverage with a clear parameter name and description ('Memory key to delete') plus an example. The description's phrase 'by key' adds no new semantic information beyond the schema, so baseline 3 applies.

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 with a specific verb ('Delete'), resource ('memory'), and mechanism ('by key'). It distinguishes from sibling tools like remember and recall by focusing on deletion, which is unambiguous and unique.

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

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

Explicitly provides when-to-use scenarios ('context is stale, task is done, clear sensitive data') and references siblings with 'Pair with remember and recall.' This helps the agent choose the correct tool among the memory-related 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the operational behavior: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'. It also specifies the output is a 'single text blob ready to drop at site-root/llms.txt', providing more context than annotations alone. No contradictions with annotations.

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

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

The description is concise (three sentences) and well-structured, front-loading the primary purpose, then explaining the process and output, and ending with concrete use cases. Every sentence earns its place with no redundancy.

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

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

For a tool with 2 parameters and no output schema, the description is complete: it explains what the tool does, how it works, the output format, and when to use it. The absence of an output schema is compensated by the explicit 'single text blob' statement. The annotations further cover safety traits, so no critical information 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 description coverage is 100%, with both 'url' and 'max_links' already clearly described. The description adds minimal semantic value beyond the schema—it mentions 'any URL' and 'key links' but does not elaborate on parameter details or defaults. Baseline 3 is appropriate when the schema carries the burden.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It further details the process (fetches page, extracts title/description/key links) and the output format, making it unmistakable from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence'.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. It does not mention exclusions or alternatives, but the use cases are sufficiently specific for a simple tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds contextual detail that the id is an NYPL item uuid from search, but does not disclose return format, pagination, or rate limits; however, given the strong annotations, this level of additional detail is adequate.

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, front-loaded sentence with no redundant words. It begins with the verb and directly states the resource and key parameter, making it maximally efficient.

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

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

The tool is simple with one required parameter and strong annotations covering safety. The phrase 'Fetch full details' implies the return content, and the description provides sufficient context for use. A minor omission is not describing the exact return structure, but given the tool's simplicity, this does not hinder understanding.

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

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

Schema description coverage is 100%, with both id and _apiKey documented in the schema. The description adds a small semantic cue by noting the id is an NYPL item uuid from search, which helps an agent understand the id's provenance, but it does not substantially go beyond the schema.

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

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

The description uses the specific verb 'Fetch' and identifies the exact resource ('full details for one NYPL Digital Collections item'), clearly distinguishing it from sibling tools like search or entity_profile. It also specifies the required identifier ('NYPL item uuid'), leaving no ambiguity about what the tool does.

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

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

The description states that the id comes 'from search', giving clear context that this tool is used after a search operation, not for searching itself. It stops short of explicitly naming alternatives or exclusions, but the prerequisite is well implied.

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, and non-destructive. The description adds value by disclosing the response shape (id, type, params, created_at, last_fired_at, fire_count) and scoping to the caller's own subscriptions. 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?

Two sentences, front-loaded with the core action, then return fields, then explicit usage guidance. Every clause serves a purpose and there is zero 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?

For a simple list operation with one optional parameter and no output schema, the description fully compensates by naming all return fields. It also connects to sibling actions, making the overall context complete.

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

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

The sole parameter (include_inactive) has a full description in the schema, reaching 100% schema_description_coverage. The description adds no extra parameter semantics, but the baseline of 3 applies because the schema carries the burden adequately.

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

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

The description uses a specific verb 'List' with a clear resource ('the caller's active subscriptions') and enumerates the exact return fields. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by explicitly framing its role as reviewing active 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 explicitly states when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for both pre-subscription review and pre-unsubscription lookups, effectively ruling out misuse.

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

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

Annotations are all false and offer no safety hints, but the description discloses side effects and operational constraints: it returns a claim_token, is rate-limited to 5 per identifier per day, is free, doesn't count against quota, and the team reads digests daily. It also describes the follow-up claim_token workflow.

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

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

The description is front-loaded with the core purpose, then systematically covers usage exclusions, token workflow, rate limits, and quota impact. Every sentence contributes distinct information without redundancy, earning 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?

For a side-effecting feedback tool with no output schema and no annotation hints, the description provides complete operational context: when to use, what to include, what to avoid, rate limiting, and the claim_token lifecycle. The agent can invoke this tool correctly without additional external knowledge.

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, and the description adds practical semantics for claim_token (pass back later to read fix status), message specificity, and optional context fields. While the schema already documents claim_token's read behavior, the narrative ties parameters into a workflow.

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 phrase ('Tell the Pipeworx team... is broken, missing, or needs to exist') and enumerates feedback types (bug, feature/data_gap, praise), clearly distinguishing this feedback channel from sibling research/query 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?

Explicitly states when to use: 'Use when a tool returns wrong/stale data...', and provides a firm exclusion for tools from other MCP servers, directing the agent to file elsewhere. Also instructs on what to include (tools/packs, not end-user prompts).

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

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

Beyond the readOnly/idempotent annotations, the description adds valuable context: derived from CF analytics-engine, no PII, cached 5min-1h depending on window. This informs the agent about data freshness, privacy, and aggregation source, which annotations do not cover.

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

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

The description is well-structured and front-loaded with the core action, then lists returns, use cases, and implementation details. Every sentence adds value with no filler or redundancy.

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

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

With one simple parameter, strong annotations, and no output schema, the description covers return content (pack, tool, count), use cases, caching, and privacy. It provides sufficient information for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with a clear enum and default for 'window'. The description repeats the window options and adds caching behavior tied to the window, but this is more behavioral context than parameter semantics. Baseline of 3 is appropriate since the schema already documents the parameter fully.

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

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

The description clearly states the tool's function: returns top tools, packs, and total call volume over a window. It also explains the aggregation source and explicitly distinguishes it from mere search by focusing on what other agents are calling, which differentiates it from sibling tools like discover_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?

Provides three explicit use cases (discovering hot data sources, confirming canonical choice, aligning with agent needs) and explains window tradeoffs. However, it does not name alternative tools or state when not to use it, so it falls slightly short of the highest bar.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial behavioral detail: placeholder-slug filtering, partition filter thresholds, the fill-check logic, and the explicit warning that realizable_edge_pp <= 0 means 'do not trade it.' 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 longer than average but well-organized with labeled sections and every sentence adds operational nuance. It is front-loaded with a clear purpose sentence; however, the density is high enough that it may require careful reading to absorb all the details.

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

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

With no output schema, the description compensates by thoroughly enumerating response fields and edge-case behaviors such as skipped_low_similarity, placeholders_filtered, and thin_legs. It covers selection, invocation, interpretation, and when not to act, making it fully sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by adding mode semantics, examples for both event slugs and topic seeds, acceptance of full Polymarket URLs, and the behavioral consequences of each parameter. It also clarifies the no-argument default, which the schema does not.

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 opening sentence states a specific action and method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this from sibling tools like polymarket_edges and polymarket_fill_risk by describing concrete detection mechanisms and output signals.

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

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

The description provides explicit mode selection: no args for trending_scan, event for single-event scans, and topic for cross-event scans. It even recommends 'event (recommended for a specific market)' and cross-references polymarket_fill_risk for custom sizing, covering both when-to-use 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 already declare readOnlyHint, idempotentHint, and non-destructive, but the description adds substantial behavioral detail beyond that: caching behavior ('Cached 1h at the KV level keyed on all knobs'), why segments may be empty (via _diagnostics), the 24h-move warning ('your edge may already be in the price'), slippage assumptions, and the rare-by-design nature of concentrated longshots. There is no contradiction with annotations.

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

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

The description is dense and long, incorporating many parentheticals and embedded lists. It is organized with capitalized section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and does front-load the core purpose, but it reads as a wall of text. While every sentence contributes information, it could be restructured with bullets for readability. Thus it is not as concise as it could be.

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

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

Given no output schema and complex behavior, the description is remarkably complete: it explains the top-level response (by_segment, fed_candidates, _diagnostics), the three model families with their sub-signals, the tradeable-edge knobs, the funnel counters, and caching. It also warns about the Fed signal unreliability. This fully compensates for the lack of an output schema.

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

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

The input schema already covers 100% of parameters with detailed descriptions, so baseline is 3. The description adds extra meaning beyond the schema by explaining the interaction between min_kelly and partition overround (min_kelly never filters partitions because they return 0 at parent level) and clarifying the purpose of min_partition_leg_kelly. This adds value beyond the schema, justifying a 4.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('Built for "what should I bet on today"'), and the details on model families and response segments clearly distinguish it from siblings like polymarket_arbitrage, polymarket_edge_tracker, and polymarket_fill_risk.

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

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

The description gives clear usage context: 'agents discover opportunities without paging hundreds of markets' and describes tradeable-edge knobs for refining results. It does not explicitly name when NOT to use it or compare it to alternatives, but the Fed-bet warning ('unreliable at meeting-month horizons') provides a specific exclusion case. Thus clear context but no explicit alternative guidance.

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

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

The description goes far beyond the annotations, disclosing the response structure (tracked, expired, snapshot_dates), trend taxonomy (new | widening | stable | decaying), decay computation semantics (on |edge_pp_net|, signed by trade direction), snapshot TTL of 60 days, data gaps due to cache-miss behavior, and the fact that decay uses daily closes rather than intraday. This is rich 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 long but fully structured with sections (Args, RESPONSE, LIMITS) and every sentence earns its place. It front-loads the core question and uses formatting (brackets, arrows) for clarity. Nothing is wasted.

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 specifies the response fields and their meanings, including edge_pp_net time-series, first_seen, trend, decay_pp_per_day, expired opportunities with lifespan_days, and snapshot_dates. It also explains limitations like TTL and data gaps. This is essentially a self-contained contract.

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 for both parameters is 100%, including defaults and clamps, so baseline is 3. The description repeats the parameter info ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') but adds only marginal context by tying them to snapshot families and lookback in the response explanation. No significant value beyond schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides clear usage context by explaining when this tool is valuable ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying it should be used when edge age/decay matters. It does not explicitly name alternatives or exclusions, but the context strongly signals appropriate use cases.

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

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

The description goes far beyond the readOnlyHint and idempotentHint annotations by detailing mode-specific behavior, return fields, size interpretation, and risk of unhedged positions. It discloses that partial basket fills convert an arb into directional risk, which is critical behavioral context not present in 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 well-structured with clear mode breakdowns (SINGLE-MARKET, BASKET) and a usage directive. Every sentence provides value, though some redundancy exists (e.g., repeated warnings about thin books). It is appropriately sized for a complex tool with two modes.

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 thoroughly enumerates all relevant return fields for both modes (top_of_book, vwap_fill_price, capture_ratio, thin_legs, etc.). It also covers size limits, defaults, mode selection, and risk scenarios, making it self-sufficient for an agent to understand the tool's behavior.

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

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

Even though schema coverage is 100%, the description adds substantial meaning: it explains how 'size_usd' is interpreted differently in single-market (max spend/target proceeds) vs basket (settlement notional), clarifies default side selection, and explains the market/event mode distinction. This contextual layer is beyond the schema descriptions.

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

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

The description clearly states the tool's core function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly differentiates single-market and basket modes, each with specific verbs and outputs, and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also names alternatives and explains the risk of partial fills, giving clear context for when not to rely on theoretical edges.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context beyond these. It details response fields (leg-by-leg prices, matched spread[].top_spreads_pp), safety fields (compatibility_warning triggers, temporal_alignment), and counters (skipped_cross_type/subtype). It proactively discloses non-equivalent bet shapes and that pre-mapped topics often aren't tradeable, exceeding the annotation coverage.

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

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

The description is long but appropriately sized for the tool's complexity. It is front-loaded with the core definition, then logically organized into modes, response shape, safety fields, and caveats. Every sentence contributes meaningful information without filler or redundancy.

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

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

With no output schema provided, the description compensates by thoroughly explaining the response structure: each venue's prices, matched spread[] with Kalshi−Polymarket delta, and the safety fields. It covers compatibility_warning triggers, temporal_alignment semantics, and skip counters, giving an agent enough context to interpret results and know when spreads are meaningful.

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

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

The input schema already documents all three parameters with 100% coverage, including the list of topic shortcuts and examples. The description enhances this by explaining the interaction between parameters—how explicit kalshi_event_ticker and polymarket_event_slug override topic-mapped sides—and by framing the two modes. This adds value beyond the schema, though some information is redundant.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', which specifies the exact verb, resource, and scope. It clearly distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edges by emphasizing the cross-venue comparison and the two-mode operation.

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

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

The description explains two modes—pre-mapped topic shortcuts and explicit tickers—and when each should be used. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable', providing a clear when-not-to-rely-on-it signal. However, it does not explicitly name alternative tools for single-venue analysis or other use cases.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context: scoping to the agent's identifier, the list-all-behavior when key is omitted, and the pairing with remember/forget. It stops short of documenting missing-key behavior or broader access-control details, but the annotation coverage lowers the burden.

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 purposeful sentences, front-loaded with the core operation, followed by use case, scope, and related-tool references. Every sentence earns its place with no filler.

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

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

The tool has one optional parameter, full schema coverage, and strong annotations. The description covers purpose, use case, scope, and sibling relationships, providing an agent everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the description's parameter guidance ('omit the key argument to list all saved keys') mirrors the property description exactly. The description adds no new parameter-level semantics beyond what the schema already documents, so the baseline of 3 applies.

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: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly distinguishes the tool from siblings like remember and forget, and identifies both primary modes of operation.

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

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

Explicitly states when to use the tool: 'Use to look up context the agent stored earlier' and contrasts it with 'without re-deriving it from scratch.' It also names sibling tools as alternatives: 'Pair with remember to save, forget to delete.'

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

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

Annotations declare readOnlyHint=true, but the description explicitly describes mark_read:true as a state-changing operation that flags events as read and affects subsequent calls. This contradicts the read-only annotation. The description is transparent about the side-effect, but the mismatch between description and annotations is a serious inconsistency.

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 five sentences long, each providing essential information: purpose, return payload, filtering, mark_read behavior, and an alternative endpoint. There is no redundancy, and it is front-loaded with the primary purpose.

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

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

For a relatively simple read tool with annotations and full schema coverage, the description covers return payload, filtering, mark_read semantics, and offers a script-friendly alternative. It could explicitly mention limit and unread_only, but those are adequately described in the input schema. The annotation contradiction slightly undermines overall completeness, but it is handled in behavioral transparency.

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 extra meaning for 'type' with an example, 'since' as ISO timestamp, and explains the effect of mark_read on subsequent calls. It does not elaborate on limit or unread_only, but the schema descriptions already cover 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 uses a specific verb 'Pull' and identifies the resource as 'subscription feed', and it clarifies the return value includes alerts with payload details. It does not explicitly distinguish from sibling tools, but the purpose is clear and concise.

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

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

Provides clear context on filtering by type and since, and states that polling works fine, while also offering an alternative HTTP endpoint for scripts. It does not explicitly mention when not to use this tool versus other tools, but the usage context is reasonably clear.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses behavioral traits: it fans out in parallel, prefers GDELT but falls back to GNews on rate-limits or 5xx, and soft-fails for USPTO due to the PatentsView API sunset. It also mentions the output structure (changes[], total_changes, citation URIs), which adds valuable context the annotations don't provide.

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

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

The description is dense with useful information but well-structured: query examples, source behavior, parameter hints, output summary, and an explicit alternative. It front-loads the purpose and every sentence adds value; no filler or redundancy.

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

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

Even though there is no output schema, the description fully explains what the tool returns (changes grouped by source, total_changes, pipeworx:// citation URIs), how it behaves across multiple data sources, and when to use an alternative. It gives enough context for an agent to invoke it correctly without needing additional 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?

The input schema already documents all three parameters with full descriptions (100% coverage), so the baseline is 3. The description adds value by showing `since` usage examples ('ISO date or relative shorthand') and recommending '30d' or '1m' for typical monitoring. It also clarifies `value` accepts ticker or CIK, though this mirrors the schema. Overall it enriches the parameter guidance enough to warrant a 4.

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

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

The description states a clear, specific purpose: it is a change feed for a company over a recent window, with concrete natural-language triggers ('What's new with X'). It explicitly names the fan-out sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes itself from the sibling entity_profile tool, so the agent knows exactly what it does and how it differs.

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

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

The description provides explicit when-to-use guidance via example queries and clearly directs to an alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also gives typical `since` values ('30d' or '1m') and notes fallback behavior, giving the agent clear decision criteria.

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

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

Annotations already indicate idempotency and non-destructiveness, but the description adds valuable behavioral context: storage as a key-value pair scoped by identifier, and persistence differences between authenticated users (persistent) and anonymous sessions (24 hours). This goes beyond annotations and does not contradict them.

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

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

The description is three sentences long and efficiently covers purpose, usage, scoping, persistence, and sibling relationships. It is front-loaded with the action ('Save data') and contains no filler or redundant restatement of the title.

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 two-parameter tool with no output schema, the description is quite complete: it explains purpose, when to use, storage behavior, and related tools. It does not describe the return value, but the tool's simplicity and annotations make this a minor gap rather than a critical omission.

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

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

The schema already provides 100% coverage for the two parameters with descriptions and examples. The description adds conceptual meaning by framing the parameters as a key-value pair scoped by the agent's identifier, which helps the agent understand how to structure keys and values beyond the schema's basic definitions.

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

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

The description uses the specific verb 'Save' and clearly identifies the resource (data for later reuse), immediately making the tool's function obvious. It also differentiates from siblings by explicitly referencing recall and forget, stating 'Pair with recall to retrieve later, forget to delete,' which distinguishes it from those alternatives.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It also names related tools for retrieval and deletion, giving the agent alternatives. However, it does not state when not to use the tool, so it lacks a complete exclusion 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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it auto-disambiguates inputs, returns citation URIs, and cascades through several endpoints internally. It does not discuss error cases or rate limits, but the added context exceeds the baseline 3.

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

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

The description is somewhat long but well-structured with front-loaded examples and clear sections for supported types. Every sentence serves a purpose—providing usage context, return values, or behavioral notes. It is efficient enough for an AI agent to parse quickly, though it could be slightly tightened.

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

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

With no output schema, the description fully explains return values for both entity types, including the specific identifiers and citation URIs returned. It also mentions internal cascading behavior, which helps set expectations for performance. Given the tool's simplicity (2 parameters), this is complete and self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant extra meaning: it enumerates supported types, provides concrete examples (e.g., ticker, CIK, brand/generic names), and mentions auto-disambiguation. This goes beyond the schema's simple property descriptions, justifying a 4.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides specific examples and differentiates from siblings by saying 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource+outcome, clearly distinguishing it from other tools like search or entity_profile.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains what each type returns, implying when it is appropriate. However, it does not explicitly mention when not to use it or alternative tools for other scenarios, so it falls short of a 5.

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

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

The description discloses that it 'Probes each entity with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and 'Returns ranked list with score, confidence, signal density per entity.' This goes beyond the annotations (readOnly, openWorld, idempotent, destructive) by revealing the internal mechanism and return format. It does not mention rate limits or failure modes, but these are partially covered by the schema and annotations. 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 three sentences that are front-loaded with the core purpose, then process, then use case. There is no waste or repetition; every sentence adds value. It is appropriately sized for a composite tool.

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

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

Given the tool's moderate complexity (4 params, 1 required, no output schema), the description is complete. It covers purpose, process, output shape, and a concrete use case. It also references ai_visibility_check, allowing the agent to understand the underlying primitive. The schema and annotations fill in remaining details.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant parameter-specific meaning beyond what the schema already provides; it mentions 'your brand + N competitors' but the schema already explains first entry as subject. No additional clarity is offered for models, _apiKey, or 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 the specific verb 'Compare' and clearly states the resource: 'AI visibility across multiple entities side-by-side.' It also describes the output (ranked list) and gives an example question, distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (general comparison). This is a clear, non-tautological statement of purpose.

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

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

The description explicitly mentions a use case ('competitive AI-marketing audits') and provides an example question ('does Claude know about us as well as our competitors?'). However, it does not explicitly exclude single-entity checks or name alternative tools (e.g., ai_visibility_check) for when to use them instead. Clear context but no 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?

Discloses behavioral traits beyond annotations: fan-out across multiple data sources, partial failure degradation, bundlephobia timeout (5-30s), and sources_failed handling. This adds valuable context not captured by readOnlyHint, openWorldHint, or idempotentHint.

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

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

Four sentences, each packed with distinct information: purpose, usage trigger, ecosystem scope, return payload, and failure behavior. No redundancy and front-loaded with the main action.

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 enumerates all return fields (summary block with license, bundle_kb, tree_shakeable, etc.) and notes failure behavior. This makes the tool's capabilities and limitations fully transparent 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?

The schema already describes both parameters with 100% coverage (package name, scoped packages accepted, version defaults). The description adds no additional parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's composite purpose: a 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It uses a specific verb ('scan') and resource ('dependency'), and distinguishes from siblings by explicitly limiting to the NPM ecosystem.

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

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

Explicitly provides when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small"' and gives an alternative path for non-NPM ecosystems (deps.dev:version directly). This is clear and actionable.

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

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

Annotations already declare this as a safe, read-only, idempotent operation. The description adds value by disclosing the return fields (ids, titles, creators/sources, dates, links) and suggesting how to use the ids with the 'item' tool. No contradictions with annotations.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource. Every clause adds useful context (return fields, related tool reference), and there is 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?

Despite having no output schema, the description lists the key return fields and mentions how to proceed with results. Combined with schema details for page/limit and the read-only annotations, the description is sufficient for a straightforward search tool, though it lacks mention of sort or filtering behavior.

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

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

Schema coverage is 100%, so each parameter has a description. The tool description does not add meaning beyond what the schema already provides; 'by keyword' mirrors the query parameter description, and no additional syntax or format details are given.

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

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

The description uses a specific verb ('Search'), a clear resource ('NYPL Digital Collections collection'), and a method ('by keyword'). It also mentions returning item ids and directs users to pass an id to the 'item' tool, distinguishing it from the sibling tool 'search_within'.

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

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

The description implies usage for keyword-based search on NYPL Digital Collections, but does not explicitly state when to use this tool over alternatives or provide any exclusions. It offers a hint about using returned ids with the 'item' tool, but no direct when-to-use guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantive behavior: BGE-base-en embeddings, cosine similarity on 500-char overlapping windows, 200K-char cap with truncation and flagging, and the return format (passages with offsets + scores). No contradiction with annotations.

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

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

Three sentences, front-loaded with the core function, then usage, then technical cap. Each sentence carries unique information with no filler, making it efficient 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?

No output schema exists, but the description compensates by specifying the return format (top-N passages with character offsets and similarity scores). It also covers limits, pairing with a sibling tool, and technical details, making the tool fully self-explanatory.

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 both 'text' (e.g., SEC 10-K body, article, long tool result) and 'query' (e.g., 'supply-chain risk', 'drug interactions with warfarin'), making parameter semantics more concrete and actionable than the schema alone.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' clearly identifying the verb (search) and resource (a fetched record). It differentiates from sibling tools by emphasizing it operates on already-pulled text rather than external sources, and specifies the return of top-N passages with character offsets.

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 when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages). It also pairs with ask_pipeworx_grounded, giving the agent a clear workflow: fetch, search within, then ground over passages.

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?

With only basic hints (readOnly=false, idempotentHint=true, destructiveHint=false), the description carries substantial weight and adds rich behavioral detail: auth requirements, anonymous/BYO limitation, feed always-on behavior, SMS verification and cap, webhook signing secret returned once, and auto-disable after 10 failing webhook runs. No contradiction with annotations; the idempotentHint is not contradicted by the description.

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 dense and front-loaded with the core purpose. It packs type examples, requirements, and channel behavior into a compact block; every clause adds necessary context for a multi-type subscription tool. Slightly verbose due to overlapping examples with the schema, but appropriate for the complexity.

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

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

For a subscription-creation tool with no output schema, the description is unusually complete: it states the return value, required auth, all subscription types (including extras like patent_grant and clinical_trial visible in the schema), and delivery options with edge cases such as webhook auto-disabling. No major gap remains for 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%, so the schema already documents all properties. The description adds useful semantic examples beyond the schema, such as items:['5.02'] = officer change and params:{topic:'fed'} for polymarket_edge, plus delivery channel constraints. These examples enrich meaning, though much of the detail overlaps with 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 opens with a specific action and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes itself from siblings like list_subscriptions and unsubscribe by stating it returns a new subscription id and by enumerating supported subscription types and delivery channels.

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

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

The description provides clear context: this is for proactive monitoring, requires a Pipeworx OAuth account, and gives channel-specific prerequisites (e.g., phone verified for SMS, 10/day cap). It does not explicitly name alternative tools for one-off queries, but it does say the feed can be pulled via recent_alerts, which implies the consumption path. This is clear context but lacks explicit 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 convey read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: it reveals the tool returns 'category-bucketed example questions' and that data is 'drawn from the live catalog of thousands of tools', which implies dynamic content. This is useful behavioral detail without contradicting annotations.

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

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

The description is detailed but well-structured, with the key purpose stated up front and usage rules following. The opening list of example queries (e.g., 'what can you do?') is slightly verbose but serves as useful NLP cues. Every sentence contributes, though the list could be trimmed for tighter conciseness.

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 compensates by stating what is returned ('category-bucketed example questions') and their content ('exact tool + argument shape'). It covers purpose, usage, parameter behavior, and even alternatives, making it fully complete for an onboarding 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?

The schema already describes `topic` with 100% coverage, so the baseline is 3. The description enriches this by providing concrete example values ('finance', 'pharma', 'betting') and explaining the effect ('focus' vs. 'full spread'), adding value beyond the schema.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions with tool mappings. It uses a specific verb ('returns') and resource, and distinguishes itself from siblings by explicitly saying 'Use this FIRST' and naming meta-tools it teaches (ask_pipeworx, entity_profile, 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 gives clear usage context: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the parameter choice (no arguments vs. topic). It lacks an explicit when-not-to-use statement, but the 'FIRST' priority implies it's not for advanced users, so it's strong but not perfect.

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 non-read-only, non-destructive, idempotent, and open-world hints. The description adds crucial context beyond these: ownership is enforced, the row is deactivated rather than deleted, and historical events remain available via recent_alerts. This meaningfully discloses side effects and safety posture without contradicting annotations.

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

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

The description is two sentences long, front-loaded with the action, and contains no unnecessary words. Each sentence adds value: the first defines the operation, the second explains side effects and restrictions.

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

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

For a simple one-parameter mutation tool, the description covers the key aspects: what it does, ownership, and persistence behavior. It omits return value or error handling details, but these are not critical for selecting and invoking the tool, especially given the rich annotations and straightforward schema.

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

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

The input schema fully documents the single parameter 'id' with a description ('Subscription id (uuid) returned by subscribe'). The description adds no new parameter details beyond what the schema already 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 begins with a specific verb 'Cancel' and a clear resource, 'subscription by id.' It directly addresses the tool's purpose (unsubscribe) and differentiates from siblings by explicitly mentioning subscribe and recent_alerts, linking it to related operations.

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 clearly implies when to use this tool (to cancel a subscription) and includes an important constraint (ownership enforcement). However, it doesn't explicitly mention when not to use it or point to alternatives like list_subscriptions for finding subscription IDs, leaving some implicit guidance.

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

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

Annotations already cover readOnly/openWorld/idempotent safety. The description adds meaningful behavioral context: the five verdict types, inclusion of a pipeworx:// citation and reasoning, the tolerance cap, and the automatic fallback pipeline. This goes beyond annotations, though it doesn't discuss failure modes or rate limits.

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

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

The description is information-dense and well-organized: query examples, usage trigger, routing logic, return contract, and efficiency benefit. It is somewhat long, but every sentence contributes necessary context for a tool with no output schema.

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 enumerates the verdict types and result components (actual value, citation, reasoning), and explains the two routing paths. This gives enough to predict behavior for both financial and general claims. Minor gaps: exact meaning of 'inconclusive' vs 'unsupported' is not differentiated.

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 practical nuance: tolerance_pct overrides the tolerance implied by wording, suggests 1–2 for hallucination detection, and notes the default cap at 5. This is genuinely useful beyond the schema's plain 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 opens with concrete natural-language examples and defines the tool as 'natural-language claim verification against authoritative sources.' It clearly distinguishes this from sibling tools by positioning it as a claim-verification tool that replaces multi-step lookup pipelines, not a general search or research tool.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies two routing paths (SEC EDGAR/XBRL for financial claims, grounded pipeline otherwise). It does not explicitly name alternative sibling tools or state when not to use it, so it falls short of a 5.

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