Dryad

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

Annotations already convey safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: the default model is free, Anthropic requires a BYO key with direct billing, and the return format includes per-model fields. 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 very concise (two sentences), front-loads the action and output, and uses clear, direct language. Every sentence adds essential information without 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?

Despite having no output schema, the description sufficiently describes return values (per-model score, confidence, signals, raw_response + combined view). Use cases are provided. Minor gaps: no mention of pagination or rate limits, but overall complete for a non-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?

Schema descriptions cover all parameters (100% coverage), so baseline is 3. The description does not add significant meaning beyond stating the default model and the role of _apiKey, which is already implied in the schema. Minimal added value.

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

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

The description clearly specifies the verb 'probe' and the resource 'LLMs', details the output as a visibility score (0-100) per model, and lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). This makes the tool's purpose distinct and actionable.

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 contexts for use (AI-marketing audits, pre-launch brand checks, competitive monitoring). However, it does not guide when to avoid this tool or suggest appropriate sibling alternatives like 'scan_competitor_ai_presence' for competitor-specific checks.

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 behavioral context beyond annotations: it routes questions, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also notes it works on every tier. This complements the readOnly/openWorld/idempotent hints without contradicting them. Missing details like rate limits or failure modes, but annotations cover safety.

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

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

While relatively long, the description is front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH'), and every sentence conveys a distinct useful fact. It avoids fluff and includes examples, alternatives, and a clear start-here directive. The structure is logical, moving from primary usage to escalation paths.

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

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

For a single-parameter tool with no output schema, the description covers all necessary context: what it does, when to use it, how to frame questions, what output to expect (structured answers with citations), and how it differs from siblings. It also addresses breaking news and real-world data, making it a complete guide.

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% as all parameters are aliases for the question field. The description adds value by clarifying the expected input ('natural language' question) and providing real-world examples. It also explains that aliases are accepted, which aligns with the schema. The description enhances rather than repeats 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: to answer factual questions by routing to thousands of verified sources and returning structured answers with citations. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its unique role explicit.

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

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

The description provides explicit usage guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It specifies when to use alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions) and gives concrete examples. This is model 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 adds context beyond annotations by explaining it is a full working router, not a fallback, and that routing improvements are enabled live. It also discloses that currently no candidate is active, so behavior matches the stable router. This goes beyond the basic read-only/idempotent hints.

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

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

The description is structured with the core purpose first, followed by current status and usage. It is fairly concise, though the specific date of the last retired candidate adds detail that may become outdated. Overall, every sentence contributes useful context.

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

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

Given the tool's complexity as a universal router, the description provides sufficient context: relationship to the stable version, experimental nature, current equivalence, and usage guidance. The absence of an output schema is mitigated by the mention of identical response shape, making the description complete enough for an agent.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description itself does not add further parameter details, but the schema fully handles the semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing its experimental nature and current live routing improvements.

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 given: use it exactly like ask_pipeworx when wanting the newest routing. It also notes that results are compared against the stable router for merge decisions. However, it could more explicitly state when not to use it or contrast with other siblings like ask_pipeworx_grounded.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these hints, including the refusal reasons (e.g., not_in_source, tool_error), the rule of using ONLY tool result content, and the extra LLM call cost. No contradiction exists.

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

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

The description is relatively long but every sentence serves a purpose: purpose, mechanism, return format, refusal behavior, usage guidance, and cost comparison. It is front-loaded with the primary purpose and is structurally organized, making it dense yet scannable.

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

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

The description fully covers the tool's behavior, including routing, extraction constraints, output schema (success and refusal variants), typical use cases, and cost implications. No output schema exists, so the description carries the full burden, and it succeeds in providing a complete picture.

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

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

Schema coverage is 100% with all parameters being aliases for 'question' and fully described. The description does not add any parameter-specific semantics beyond the general notion of a natural-language question; the schema already handles this, 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 this is a 'hallucination-resistant answer mode for high-stakes reads' and explains that it extracts answers only from tool results, distinguishing it from sibling ask_pipeworx. It explicitly differentiates from the sibling by mentioning cost and use cases, so it earns a 5.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also provides a clear alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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

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

The description extensively discloses behaviors beyond annotations: fan-out logic, resolver contract with confidence levels, parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed/dead market handling), wide-spread market warnings, and resolution-rule risk parsing. It aligns with annotations (readOnly, openWorld, idempotent, non-destructive), adding rich context.

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

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

The description is front-loaded with the main purpose, and uses clear section headers (e.g., RESPONSE SHAPES, RESOLVER CONTRACT) for complex details. While lengthy, the verbosity is justified by the tool's complexity. Could be trimmed slightly, but remains well-organized and accessible.

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 (market resolution, classification, fan-out, safety checks, risk parsing) and lack of an output schema, the description covers all necessary aspects comprehensively. It explains response shapes, edge cases, and failure modes, making it complete for effective use by an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the market parameter's flexibility (slug, URL, question text) and providing examples. It also contextualizes the depth parameter through fan-out examples and explains the include_raw parameter's effect on response size. This enhances understanding 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 purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet, comparison). The use cases ('should I bet on X', etc.) differentiate it from sibling tools like polymarket_edges, which likely provide edge lists rather than single-bet research.

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

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

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 use the tool. However, it does not explicitly mention when not to use it or direct alternatives from the sibling list, so it 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?

The description discloses behavioral traits beyond annotations: e.g., it pulls LATEST 10-K data for companies (handling off-calendar fiscal years), FAERS data for drugs, sorts results by primary metric, and returns citation URIs. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is well-structured with examples, separate handling of type, and front-loaded key guidance. Every sentence adds value (e.g., 'Replaces 8–15 sequential lookups'), and it remains focused without extraneous information.

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

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

Given no output schema, the description explains return format (paired data + citation URIs) and sorting behavior. It covers both entity types comprehensively, making the tool fully understandable for an AI 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?

With 100% schema coverage, the description adds value by explaining the type parameter's data scope (e.g., company: SEC EDGAR/XBRL; drug: FAERS) and providing concrete examples for values (tickers for company, drug names). It clarifies the max/min constraints already in schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, with explicit example queries like 'compare X and Y' and 'which is bigger'. It distinguishes from sibling tools by advising 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

The description provides explicit when-to-use guidance (head-to-head comparisons, rankings) and warns against sequential lookups. It details context for company vs drug data, including specific data sources and metrics, ensuring appropriate selection.

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

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

Beyond the readOnly/openWorld annotations, the description discloses rich behavioral detail: returns a findings packet with verbatim evidence, confidence, gaps[], contradictions[], never invents answers, semantically excerpts long records, and provides resolvable citation URIs. It also explains the hop-based depth mechanics and expected latency (~15-90s).

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 with no filler; every sentence adds value. It is front-loaded with the access prerequisite, then describes functionality, guidance, and behavioral nuance. A bit more structural formatting (paragraphs/bullets) would improve scannability, but given the tool's complexity, the length is justified.

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

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

With no output schema, the description fully compensates by detailing the return packet structure (evidence + confidence + source + fetched_at + citation), the gaps[] and contradictions[] arrays, citation resolvability, and operational expectations like account tiers and latency. It is self-sufficient for an agent to invoke and interpret results.

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

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

Schema coverage is 100% and both parameters are already well-described (question natural language, depth with detailed hop semantics). The description adds example research questions and reiterates depth behavior but does not add new syntax or format information 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 function: 'Grounded multi-source research across Pipeworx's 1428 STRUCTURED data sources' in one call, and explicitly distinguishes itself from open-web search and sibling ask_pipeworx. It uses a specific verb (research) and resource (structured data sources) with clear scope.

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

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

The description gives explicit usage guidance: best for 'broad/multi-part questions over structured data', alternatives for single lookups and breaking news, and a direct warning to use ask_pipeworx when not signed in. Depth options and account restrictions are also clearly stated.

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, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N relevant tools with full schemas and curated examples, ready to call directly. No contradictions.

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

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

Two sentences, front-loaded with purpose, then usage guidance. Every sentence provides essential information with no waste.

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

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

Given 6 parameters, many siblings, and no output schema, the description fully covers return format, usage context, and when to call. Complete for a discovery tool.

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

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

Schema coverage is 100% with all 6 parameters described. The description mentions aliases but adds little beyond schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Find tools by describing the data or task' and lists numerous example domains (SEC filings, FDA drugs, etc.), clearly distinguishing it from sibling tools which are specific data 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?

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance and implies 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?

Description adds significant behavioral context beyond annotations: parallel fan-out across multiple sources, patent sunset detail, return fields (CIK, filings with URIs, fundamentals sorted), and soft-fail behavior. No contradiction with annotations.

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

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

Description is a single paragraph with front-loaded examples and clear structure, but could be broken into bullet points for even easier scanning. Still efficient and without wasted words.

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

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

Given complexity (multiple data sources, no output schema), the description thoroughly explains all return components and limitations (patent sunset, name unsupported). An AI agent can fully understand the tool's behavior and output.

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

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

Schema coverage is 100% and descriptions are already informative. The description adds extra context: 'type' limited to 'company', 'value' must be ticker or CIK, and specifically warns that names are not supported. This exceeds the baseline of 3.

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

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

The description clearly states the tool provides a holistic cross-source profile of a US public company, with specific examples ('Tell me about X', 'brief me on Tesla') and explicitly distinguishes itself from chaining single-pack lookups.

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

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

Explicitly advises use when a holistic view is requested, and directs to resolve_entity for names. Also mentions soft-fail for patents and lists data sources, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data but does not detail edge cases like missing keys. No contradiction.

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

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

Two concise sentences with zero waste. Front-loaded with the action and 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 tool with one parameter and no output schema, the description fully covers when, what, and with which siblings. No gaps remain.

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

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

Schema coverage is 100% with a clear description 'Memory key to delete.' The description adds 'by key' but no new semantic 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 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember and recall'.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and idempotency. The description adds behavioral context (fetches page, extracts info, emits text) 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 a single paragraph of ~60 words, front-loading the main purpose and covering output format and use cases. Every sentence earns its place without 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 tool with 2 parameters and no output schema, the description fully covers functionality, output format, and usage contexts. Annotations provide additional safety info. No gaps.

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

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

Schema coverage is 100%, with both parameters described. The description adds context about max_links defaults (25) and max (50) but does not provide significant additional meaning beyond the schema.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the process (fetches page, extracts title/description/key links) and output format (standard markdown). This distinguishes it from sibling tools like scan_competitor_ai_presence.

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

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

The description explicitly lists use cases (getting client site indexed, drafting own llms.txt, auditing competitors). It provides clear contexts but does not mention when not to use the tool or name alternative tools, which would strengthen the 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=true, idempotentHint=true, destructiveHint=false. The description adds 'Keyless' (no authentication) and details the returned fields, providing behavioral context beyond annotations.

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

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

Two concise sentences: first defines purpose and input, second describes output. No extraneous information.

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

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

Given the simple tool with one parameter, strong annotations, and a clear description of return values, the description is complete enough for an agent to understand behavior and output without 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?

Schema coverage is 100% and already describes the DOI parameter. The description adds specific examples and clarifies the optional 'doi:' prefix, adding marginal 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 fetches a single Dryad dataset by DOI, returning full metadata and a download URL. It distinguishes from sibling tools like 'search_datasets' which would be for querying multiple datasets.

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 fetching a specific dataset by DOI, and mentions 'Keyless' indicating no auth needed. It does not explicitly state when not to use or recommend alternatives, but the sibling list includes search_datasets for broader searches.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it returns specific fields and lists active subscriptions by default, but does not mention pagination or rate limits. This is adequate given the tool's simplicity.

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

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

The description is two sentences, front-loaded with purpose, and contains no unnecessary words. It efficiently communicates what the tool does and when to use it.

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

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

The description provides a complete summary of the return fields (id, type, params, created_at, last_fired_at, fire_count) and usage context, compensating for the lack of an output schema. The tool is simple with one optional parameter, so the description covers all needed context.

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

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

Schema coverage is 100% with a clear description for the single parameter 'include_inactive'. The tool description does not add additional parameter semantics beyond what the schema provides, so baseline score 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It lists the returned fields and distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing.

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 this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear when-to-use guidance and implies when not to use (e.g., when subscribing or unsubscribing).

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, so the description carries the burden. It richly discloses side effects: report is read daily, rate limit (5/day/identifier), free, returns a claim_token for follow-up, and instructs not to paste the end-user's prompt. 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 earns its place: purpose, use cases, exclusions, token flow, team process, rate limit. It is front-loaded with the verb and target, making it easy to scan.

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

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

Despite having no output schema, the description explains the return token mechanism and follow-up flow, covers exclusions and constraints, and provides enough context for an agent to decide when to use it. It fully handles the complexity of four optional params and a nested context object.

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 params, so baseline is 3. Description adds extra meaning by explaining that filing without an account yields a claim_token and how to use it later, and advises describing issues in terms of Pipeworx tools/packs rather than end-user prompts — guidance not present in schema.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates use cases (bug, feature/data_gap, praise) and distinguishes this from sibling research/visibility tools like ask_pipeworx or deep_research by framing it as a feedback channel, not a query 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?

Provides explicit when-to-use guidance with examples ('Use when a tool returns wrong/stale data...'), an explicit exclusion for tools from other MCP servers ('file it with that server instead'), and a disambiguation rule ('Pipeworx tool names are the ones this connection lists'). 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 declare readOnly, openWorld, idempotent, non-destructive. Description adds source (CF analytics-engine), no PII, and caching duration (5min-1h), which are valuable beyond annotations.

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

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

Two sentences plus a bullet-like list. Every sentence adds unique value: purpose, use cases, data source, caching. No wasted words.

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

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

For a simple one-param tool with no output schema, the description fully covers purpose, usage, data provenance, and caching behavior. Agent has all needed info.

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 description for 'window'. Description adds nuance: 'shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Clear verb+resource: 'returns the top tools, top packs, and total call volume over a recent window.' Distinguishes from siblings like discover_tools by focusing on trending/call volume.

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

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

Explicitly lists three use cases (e.g., discovering hot data sources, confirming canonical choice). No explicit when-not-to-use, but contexts are well-defined.

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

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

The description discloses behavioral traits beyond annotations: it walks child markets, computes partition checks, filters placeholders, uses Jaccard similarity, and performs fill checks. No contradiction with annotations (readOnly, idempotent, etc.).

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

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

The description is well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the main purpose. It is slightly verbose but every sentence is informative. Could be more concise but still effective.

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

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

Given the complexity of the tool (multiple modes, filtering, fill checks), the description is complete. It describes response structure, edge cases (e.g., placeholder filter), and cross-event matching criteria. No output schema but the description compensates.

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?

While the schema already has descriptions for both parameters, the tool description adds significant context: examples of slugs, seed questions, filtering logic (semantic anchor, partition filter), and the fill check. It greatly aids understanding beyond the schema.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and contrasts with siblings by specifying its unique functionality.

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 each mode: no args for trending scan, 'event' for per-event partition check, 'topic' for cross-event scan. It also warns when not to trade (realizable_edge_pp ≤ 0) and suggests polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral detail: three opportunity segments with mathematical models, tradeable-edge knobs, response structure with diagnostics for empty segments, and caching behavior. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded purpose. Some technical details (e.g., FRED log-returns, per-sport α) may be excessive for an agent, but they serve transparency. Generally concise relative to complexity.

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

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

Given 9 parameters, no output schema, and nested response objects, the description thoroughly covers response structure (by_segment, fed_candidates, diagnostics), explains why segments may be empty, and details tradeable-edge filters. Annotations cover safety. No significant gaps.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds value by grouping parameters as 'TRADEABLE-EDGE KNOBS' and explaining their purpose in the filtering pipeline, which is not present in the schema. This conceptual grouping enhances understanding beyond the individual parameter 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 scans Polymarket markets for edge opportunities where Pipeworx data disagrees with market price, specifically for the 'what should I bet on today' use case. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven and structural arbitrage 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 explicit context for use ('what should I bet on today') and mentions that Fed bets are excluded from ranking due to data reliability. While it does not directly contrast with siblings, the detailed model families and knobs imply usage scenarios, and the caching note helps manage expectations.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description adds significant behavioral context: response structure (tracked, expired, snapshot_dates), meaning of negative edge_pp_net, limitations (60-day TTL, snapshot gaps, decay computed from daily closes not intraday). This fully informs the agent of 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 information-dense but well-structured: starts with purpose, then details response fields, then limitations. Every sentence adds value. Slightly verbose but acceptable given 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?

Given no output schema and only two primitive parameters, the description provides complete context including return structure, field meanings, trade interpretation ('a fresh wide edge and a 3-week-old wide edge are different trades'), and data limitations. No gaps remain.

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 extra value beyond schema: default values (days=14, window='1wk'), maximum days (30), and acceptable window values ('24hr | 1wk | 1mo'). This enhances understanding.

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

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

The description clearly states the tool tracks edge persistence and decay telemetry. It uses a specific verb ('answers') and resource ('edge persistence and decay telemetry') and distinguishes itself from the sibling 'polymarket_edges' by focusing on history and decay. The concept of a fresh wide edge vs an old wide edge is explained, making the purpose very 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?

The description implies usage context: when you need edge history and decay, instead of raw snapshots (polymarket_edges). It does not explicitly state when not to use it, but provides enough context for an agent to infer appropriate use.

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

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

Annotations already include readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context such as the order book depth check, the risk of partial fills, and the forced_directional_risk naming. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections for SINGLE-MARKET and BASKET, and each sentence adds value (e.g., output fields, default values, risk warnings). Could be slightly more concise but info density is high.

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 tool complexity (two modes, many output fields) and absence of an output schema, the description thoroughly explains all return values (top_of_book, vwap_fill_price, slippage_pp, etc.) and provides risk context (thin_legs, forced_directional_risk). It is complete for effective selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds further context by explaining the interplay between market and event parameters, default side selection for baskets, and how size_usd is interpreted differently in each mode, enhancing the schema 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 clearly defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific output fields. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk and order book depth.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns that partial basket fills convert arb into unhedged directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only and idempotent. The description adds context beyond annotations: compatibility warnings, temporal alignment, skipped cross-type/subtype counters, and the fact that real spreads are rare. 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 extensive but well-structured with clear sections (modes, response, safety fields). Every sentence adds value, though it could be slightly more concise without losing critical detail.

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

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

Despite no output schema, the description thoroughly explains the response structure: leg-by-leg prices, top spreads, compatibility_warning, temporal_alignment, and skipped counters. This provides complete context for an AI agent to interpret results.

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

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

Schema coverage is 100% and description enriches each parameter with examples, enumeration of topic values, and usage context (e.g., 'Overrides the topic-mapped...'). The description adds meaning beyond the schema's type/description.

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

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

The description clearly defines the tool as computing the spread between Kalshi and Polymarket for identical questions, with specific verb ('cross-venue spread') and resource ('Kalshi and Polymarket'). It distinguishes from sibling tools like polymarket_arbitrage by explicitly mentioning cross-venue comparison and safety fields.

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 (topic shortcuts vs explicit tickers) and when to use each. It warns that pre-mapped topics may not always yield tradeable spreads, guiding the AI when not to rely on results. No additional alternatives needed.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral details like scoping to identifier and listing all keys when key is omitted, providing valuable context beyond annotations.

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

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

Two sentences, no wasted words, front-loaded with the core action. Efficient and clear.

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

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

Given one optional parameter, no output schema, and high schema coverage, the description fully explains the tool's behavior, scope, and usage context.

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

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

Schema coverage is 100% for the single parameter. Description adds meaning by explaining that omitting the key lists all saved keys and that key is a memory key, 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 specifies the verb 'retrieve' and the resource 'value previously saved', and distinguishes the behavior when key is omitted (list all keys). It differentiates from sibling tools like remember and forget.

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

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

Provides explicit use context: 'to look up context the agent stored earlier' with concrete examples. Mentions scoping and pairing with remember/forget, but lacks explicit when-not-to-use.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description reinforces this by noting polling works fine and flags the non-destructive state change of 'mark_read'. No contradictions; adds clarity about the underlying feed being the same as a REST endpoint.

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

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

The description is a single paragraph, but it efficiently packs essential information without unnecessary words. Could benefit from slightly more structure (e.g., splitting filtering and return details), but it remains concise and effective.

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

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

Given no output schema, the description adequately explains return fields. It covers all key aspects: purpose, parameters, state effects, and alternative access. The tool's behavior is fully described 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 covers 100% of parameters with descriptions, but the tool description adds valuable context: the return format (source, citation_uri, raw payload), a type example ('sec_8k'), and explains the effect of 'mark_read' on future calls. This goes beyond the schema.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed and returns the most recent alerts with specific fields (source, citation_uri, raw payload). This is distinct from sibling tools like 'recent_changes' or 'get_dataset'.

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 filtering options (type, since) and explains how 'mark_read' works for subsequent calls. Mentions alternative access via a GET endpoint, which helps decide when to use this tool versus a script. Lacks explicit 'when not to use' but offers sufficient 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the tool's fan-out behavior to multiple APIs, fallback logic (GDELT to GNews), soft-fail for USPTO, and the return format including changes grouped by source and citation URIs. No contradictions with annotations.

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

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

The description is moderately lengthy but well-structured with examples and clarifying notes. It front-loads the core purpose and usage patterns, making it easy to scan. A minor reduction in verbosity could improve, but it is appropriate for the tool's complexity.

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

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

Given the tool's complexity, lack of output schema, and numerous sibling tools, the description provides thorough coverage: sources, parameter semantics, return structure, fallback behavior, and a clear distinction from 'entity_profile'. This enables confident selection and invocation by an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the `since` parameter's accepted formats (ISO date or relative shorthand) and suggesting common values ('30d' or '1m'). It also contextualizes how parameters are used together to retrieve the change feed.

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: providing a change feed for a company in the last N days/weeks/months across multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes from the sibling tool 'entity_profile' by noting that profile is for static information regardless of time window.

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

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

The description gives explicit guidance on when to use this tool versus 'entity_profile' and explains the news fallback mechanism. It does not explicitly state when not to use it beyond the alternative, but offers clear context for proper selection.

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

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

Adds key details beyond annotations: key-value pairing scoped by user identifier, persistence differences (authenticated vs anonymous). No contradictions.

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

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

Four concise sentences, front-loaded with purpose, efficient word choice, 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?

Fully covers usage scope, persistence, and sibling relationships given the simple key-value nature and complete parameter schema.

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

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

Schema covers 100% of parameters; description adds example keys and clarifies value as arbitrary text, enhancing usability.

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

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

Describes saving data for reuse with specific examples (ticker, address, preference). Explicitly distinguishes from siblings recall and forget.

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

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

Clear guidance on when to use (discover something worth carrying forward) and pairs with recall/forget, but lacks explicit 'when not to use'.

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

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

Beyond the read-only and idempotent annotations, the description discloses auto-disambiguation, accepted input formats (ticker/CIK/name, brand/generic), output fields (CIK, RxCUI, citation URIs), and internal cascading through endpoints. This adds substantial behavioral context beyond what annotations provide.

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

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

The description is well-structured, starting with example queries and then clearly separating purpose, supported types, and benefits. It is slightly long but every sentence contributes useful information, making it concise enough without wasted words.

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

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

Since there is no output schema, the description fully specifies return values for both entity types, including citation URIs and accepted inputs. This makes the tool's behavior complete for an agent to use correctly without needing additional information.

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 provides 100% coverage with both parameters described and examples. The description enriches this by explaining what each type returns and the accepted value formats, going beyond the schema's minimal text and helping the agent understand the parameters' purpose.

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 resolves a user-spoken name to the canonical/official identifier other tools require as input. It is specific about the verb (resolve) and resource (names to identifiers), and distinguishes itself from siblings by detailing supported types and return values.

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

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

It provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, giving clear context for when to choose it. However, it doesn't explicitly name alternative tools or exclusion criteria, so it stays just below the top score.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details: 'Probes each entity... with ai_visibility_check, ranks by score, surfaces which is most/least recognized.' It also reveals the output structure (ranked list with score, confidence, signal density), which is absent from the output schema. No contradictions.

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

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

The description is three sentences with no redundancy. First sentence states purpose, second explains mechanism, third provides use case and output format. Every sentence contributes essential information.

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

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

Given the tool's moderate complexity (4 parameters, 1 required), the description fully covers purpose, mechanism, usage context, and return format. It explains how the tool works (calls ai_visibility_check for each entity and ranks), what to expect as output, and when to use it. No gaps remain.

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%, baseline 3. The description adds value by explaining that the first entity in 'entities' is treated as the 'subject' for narrative, which is not in the schema. It also clarifies the ranking and output format. However, it does not add significant new insights for other parameters beyond the schema.

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

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

The description clearly states it 'compare[s] AI visibility across multiple entities side-by-side.' It specifies the verb 'compare' and resource 'AI visibility across entities', distinguishing it from sibling tools like ai_visibility_check and compare_entities by explaining it probes multiple entities and ranks them.

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: 'Useful for competitive AI-marketing audits' with a concrete example. It implies when to use (comparing multiple entities) and hints at when not to (use ai_visibility_check for single entities) but doesn't explicitly exclude alternatives.

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

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

Annotations indicate readonly, open-world, idempotent, non-destructive. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list for timeouts. No contradiction with annotations.

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

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

Description is front-loaded with purpose and use-case. While it is long, every sentence provides value. Some details (e.g., partial failures, timing) could be condensed but are justified given complexity.

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

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

Despite no output schema, description fully enumerates return fields (summary block, per-advisory detail, links, alternative versions). Complex multi-source tool is completely specified with no gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minor context (scoped packages accepted, version defaults to latest) but does not significantly enhance understanding beyond schema descriptions.

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

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

The description clearly states the tool's purpose as a composite check for npm package evaluation covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by specifying NPM ecosystem only and directing other ecosystems to deps.dev:version.

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 usage guidance: 'Use whenever an agent asks 'is X safe / popular / small''. Also provides exclusions (other ecosystems) and alternative tools (deps.dev:version). Mentions partial failure behavior and timing notes.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false, indicating safe, read-only behavior. The description adds that it is keyless (no authentication needed) and mentions 'truncated abstract', providing useful behavioral context beyond annotations.

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

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

Three sentences, no wasted words. First sentence establishes context (Dryad repository), second explains search capability, third lists return fields. Front-loaded with purpose and 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?

Despite lacking an output schema, the description fully explains return fields and search behavior. Combined with strong annotations (read-only, etc.), the tool is completely specified for agent use.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds value by specifying that query searches over titles, abstracts, authors, and keywords, and enumerates return fields, which is not in the schema. This helps the agent understand what the tool returns.

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

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

The description clearly states it searches Dryad, a specific repository of open research datasets from peer-reviewed studies. It explains the full-text query over titles, abstracts, authors, and keywords, and lists exact return fields (DOI, title, authors, etc.), distinguishing it from sibling tools like 'get_dataset'.

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

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

The description implies use for finding datasets in Dryad and notes it is keyless (no auth). However, it does not explicitly state when to use this tool versus alternatives like 'search_within' or 'get_dataset', nor does it provide when-not conditions.

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 important behaviors: uses BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation flagging, and returns character offsets. This goes beyond the annotations which only indicate read-only, idempotent, and non-destructive.

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

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

The description is concise yet comprehensive, covering purpose, usage, technical details, and pairing with another tool in a single paragraph. No unnecessary words; information is front-loaded.

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

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

Given the tool's complexity (3 parameters, no output schema), the description fully explains what the tool returns (passages with offsets and scores), its limitations (200K char cap, truncation), and model details. The agent has all necessary information to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by providing usage context (e.g., examples for the query parameter) and reinforcing the length cap for text. It enhances understanding beyond the schema.

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

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

The description clearly states the tool's function: semantic search inside a fetched record. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the pairing and use case.

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

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

The description explicitly tells when to use the tool: when the record is too large for the prompt. It provides context on saving prompt space and returning only relevant passages. While it doesn't list when-not-to-use, the alternative tool is mentioned.

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

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

The description adds significant behavioral context beyond annotations: it requires an OAuth account, explains the delivery channel mechanics, SMS cap, webhook auto-disable, and the one-time secret for webhooks. 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 well-structured and front-loaded, but it is verbose with detailed examples for each subscription type. While informative, some redundancy could be trimmed (e.g., repeating similar patterns). Still, the organization helps clarity.

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

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

The description covers all necessary aspects: purpose, requirements, type enumeration, parameter details, delivery options, limitations, and return value (subscription id). It is self-contained and adequate 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?

Although schema coverage is 100%, the description enriches each parameter with examples and constraints (e.g., type enum expanded with practical use cases, params structure detailed for each type, delivery channels with phone verification and rate limits). This adds substantial 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It specifies the types and delivery channels, and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains when to use the tool (creating a subscription), requirements (Pipeworx OAuth account), and provides details on delivery channels. It does not explicitly list when not to use it but implicitly through context. A higher score would require explicit alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about returning tool+argument shapes and being the onboarding entry point, going beyond the annotations.

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

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

The description is somewhat lengthy but each sentence adds value. It front-loads the purpose with common variations and is well-structured. Could be slightly more concise, but it's 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 an onboarding tool with no output schema, the description covers what it returns, the topics, tool usage examples, and when to use it. It is fully complete given the tool's purpose and context.

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

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

Schema coverage is 100% with one optional parameter. The description elaborates on the `topic` parameter by listing possible values (finance, pharma, etc.) and explaining the default behavior (cross-category spread). This adds significant meaning beyond the schema.

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

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

The description uses specific verbs ('returns') and resource ('category-bucketed example questions') and distinguishes from siblings like ask_pipeworx and discover_tools. It clearly states the tool's role as an onboarding 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and lists common user queries. It provides clear context but does not explicitly state when not to use it.

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

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

Discloses important behavior beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' No contradiction with annotations (readOnlyHint false, destructiveHint false).

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 purpose. Every sentence adds value: purpose, constraint, and effect. 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?

Simple tool with one parameter and no output schema. Description covers purpose, constraint, and side effect. Adequate for the tool's simplicity.

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

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

Schema coverage is 100% with parameter description. The tool description does not add significant new meaning beyond the schema's 'Subscription id (uuid) returned by subscribe.' Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id', distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states 'Ownership is enforced — you can only cancel your own subscriptions', providing clear context for when to use. Does not mention explicit alternatives or when not to use, but the constraint is strong enough.

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

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

Annotations already indicate safe and idempotent behavior. Description adds details on the two processing paths (SEC EDGAR vs. grounded pipeline), tolerance handling, and the return structure, providing beyond-annotation 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 paragraph is dense but each sentence adds value; front-loads purpose with vivid query examples. Could be slightly more structured (e.g., bullets) but is efficient for the amount of information.

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

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

Despite no output schema, the description fully explains the verdict types, citation, and reasoning. Covers both claim categories and mentions it consolidates multiple steps, making it complete for agent decision-making.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds practical guidance on tolerance_pct defaults and usage for hallucination detection, enhancing understanding beyond the schema.

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

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

Description starts with explicit natural-language examples and states 'natural-language claim verification against authoritative sources.' Clearly defines the tool's function and distinguishes from siblings by mentioning the structured financial fast path and that it replaces 4-6 sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Provides context on financial vs. other claims, but does not include explicit when-not-to-use or alternative tool names.

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