Dados Pt

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

Beyond annotations (safe, idempotent), description adds that it makes external LLM calls, explains cost implications for Anthropic, and describes return structure (per-model score, confidence, signals, raw_response).

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

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

Three sentences with no waste: first sentence defines purpose and output, second sentence covers configuration, third sentence lists use cases. Front-loaded 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?

Given no output schema, description sufficiently details return format and covers all parameters. Context about use cases and required fields is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, and description adds value by clarifying default model, API key purpose, and providing concrete examples (e.g., 'Pipeworx', 'Acme Corp pricing') that aid agent 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 probes LLMs for visibility scores (0-100) per model, distinguishing it from siblings like ask_pipeworx or scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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 cases (AI-marketing audits, pre-launch brand checks) and explains when to use default vs Anthropic API key, but does not mention alternatives or 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds genuine context beyond this: it discloses internal routing behavior ('routes to right one of 5,566 tools across 1462 sources'), return format (structured answer with pipeworx:// citation URIs), performance ('one fast call'), and availability ('works on every tier'). It doesn't mention rate limits or failure behavior, but for a read-only query tool this is rich disclosure that exceeds the annotation baseline. 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 logically structured (preference rule → domain list → citation benefit → trigger phrases → examples → escalation paths) but is verbose at ~280 words and leans on ALL CAPS for emphasis across three separate phrases ('PREFER OVER WEB SEARCH', 'START HERE', 'Step up only when needed'). The examples could be trimmed since the schema already provides three examples. It earns a middle score for clear organization but loses points for not being 'every sentence earns its place' — some repetition of 'authoritative structured data with citations' exists.

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 query-routing tool with no output schema, the description covers purpose, coverage breadth, return format, latency, availability across tiers, trigger phrases, and escalation paths to siblings. It doesn't explain return structure in depth, but since no output schema exists, the mention of 'structured answer with stable pipeworx:// citation URIs' is adequate context. Very complete for a tool of this complexity class.

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% for the required 'question' parameter, and the schema already documents five aliases (q, text, input, query, prompt) with descriptions. The tool description itself adds only marginal param-level meaning — example questions are in the schema's examples field rather than the description. With full schema coverage, baseline 3 applies, and the description doesn't significantly elevate understanding beyond what the schema already provides.

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

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

The description uses a specific verb+resource ('routes the question', 'returns the structured answer') and clearly scopes what it covers: SEC filings, FDA data, news, stocks, crypto, etc. It explicitly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research with their different purposes, and notes the alias ask_pipeworx_beta exists but isn't confused with it. This exceeds mere clarity and actively differentiates.

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 and immediately actionable: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and direct escalation paths ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for broad/multi-part... use deep_research'). It also gives negative guidance on when to step up or use the news-routing alternative, naming siblings explicitly. This is a textbook example of when-to-use/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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) set a baseline. The description adds significant context: it's a full working router (not a stub), candidate improvements may be active, and results feed into comparison experiments. This goes beyond annotations without contradicting them.

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

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

The description is front-loaded with the key phrase 'Beta version of ask_pipeworx' and is logically organized into a few sentences. It conveys important operational details without being overly verbose, though it could be slightly tighter.

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

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

For a router tool with a simple schema (one required parameter) and no output schema, the description covers the beta status, current behavior (matches stable), and comparison purpose. It doesn't describe return values but references 'same response shape' implicitly. Overall complete for its complexity.

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 covers all 6 parameters (question and 5 aliases) with clear descriptions. The description adds nothing beyond saying 'same arguments' as ask_pipeworx, which is redundant. High schema coverage (100%) means the baseline is 3; no additional value is provided.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same 5,566 tools and arguments. It distinguishes from siblings by explicitly comparing it to ask_pipeworx (stable) and noting the experimental routing edge. The title adds context, and the description avoids tautology.

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: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. It also clarifies that currently it matches ask_pipeworx exactly, giving a clear when-to-use vs. 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?

The description discloses key behaviors beyond annotations: it costs an extra LLM call, returns explicit refusal reasons, and only uses tool results. It aligns with annotations (read-only, idempotent) and adds valuable context about failure modes and result structure.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose, then provides details on routing, refusal reasons, usage context, and cost trade-off. Every sentence adds value, with no waste or redundancy.

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

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

Given the tool's complexity (routing, extraction, refusal modes), the description covers purpose, behavior, return format, usage scenarios, and cost implications. It also lists refusal reasons and directs to the alternative for casual lookups, making it fully self-sufficient.

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

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

The schema covers 100% of parameters, all aliases for 'question', and the description adds no parameter-specific meaning. Per the guidelines, with high schema coverage, a baseline of 3 is appropriate; the description doesn't detract but doesn't enhance parameter understanding beyond what the schema provides.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode that routes like ask_pipeworx but extracts answers solely from tool results, with explicit refusal handling. It distinguishes itself from the sibling by emphasizing groundedness and the refusal mechanism, making its purpose unambiguous.

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

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

The description explicitly states when to use ('Use whenever an answer will be quoted, cited, or acted on...') and when not to ('prefer ask_pipeworx for casual lookups'), and mentions the alternative tool by name. This provides clear selection criteria.

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

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

The description extensively covers behavioral traits beyond annotations, including fan-out logic per classifier, resolver confidence handling, parent event extraction, news fallback mechanisms, safety short-circuits, and resolution-rule risk. No contradiction with annotations.

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

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

The description is long but well-organized with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds necessary context for a complex tool, though some redundancy exists (e.g., duplicate notes on closed markets).

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

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

Given the tool's complexity and lack of output schema, the description provides complete coverage: input handling, processing steps, output structure, edge cases (closures, low confidence, wide spreads), and resolution risks. 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?

All three parameters are documented in the schema (100% coverage). The description adds value by explaining how depth and include_raw affect fan-out and response size, and clarifies the market parameter's flexibility (slug, URL, text).

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 researches Polymarket bets by pulling Pipeworx data, specifying inputs like slug, URL, or question text. It distinguishes from siblings by detailing the full research pipeline (resolve, classify, fan-out, compare), which is unique among tools like polymarket_edges.

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

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

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), along with examples per category. While it doesn't list alternatives or exclusions, the context is clear enough for an agent to determine when to invoke.

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

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

Annotations already indicate readOnly/openWorld/idempotent/non-destructive. The description adds valuable context: for company, it pulls LATEST 10-K data with fiscal year handling, and for drug, FAERS data. It also mentions results sorted by primary metric and returns citation URIs, going beyond annotations.

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

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

The description is concise (~100 words), well-structured with front-loaded trigger phrases, and every sentence adds value. No redundancy or fluff.

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

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

Despite no output schema, the description covers return format (paired data + citations), addresses complexity (off-calendar fiscal years), and explains when to use. It provides complete context for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% with descriptions for both params. The description enriches understanding by explaining what data each type pulls (e.g., company: SEC EDGAR/XBRL revenue, net income, etc.) and giving concrete examples like tickers for company values. This adds significant value beyond the schema alone.

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

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

The description starts with explicit trigger phrases ("Compare X and Y", "X vs Y", etc.) and clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from sequential single-entity lookups, making its purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also explains the two entity types (company and drug) and what data each pulls, helping the agent decide which 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 include readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: parallel decomposition, returns findings with evidence/source/citation, gaps[] for unanswered facets (never invented), hop field, contradictions[] for standard/thorough, and fetchable citation_uri. It also mentions latency (15-90s) and account/depth requirements. These go beyond annotations, though some details like 'semantic excerpting' could be considered extra but are valuable.

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

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

The description is lengthy and dense, covering many details (account requirements, examples, exclusions, latency, semantics). While each sentence has value, the structure is a single large paragraph that may overwhelm the agent. It lacks front-loading of the most critical purpose; the purpose is stated after several clauses. It earns a 3 for being information-rich but poorly structured.

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

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

Given the tool's complexity (composite research with multiple hops, contradictions, citations) and the absence of an output schema, the description provides thorough context: what the tool does, how it works, what the findings packet contains, what to expect in terms of gaps and contradictions, and latency. The high schema description coverage covers parameters, and the description fills in the behavioral context comprehensively.

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 description coverage is high (100%) and provides clear parameter descriptions for 'question' and 'depth' (including enum values and their behavior). The description adds context about depth levels ('standard' vs 'thorough' and gap recovery) but largely reiterates what the schema already communicates. With high schema coverage, baseline is 3, and the description adds slight value by explaining expected latency and second-hop iteration.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, distinguishing it from open-web search and sibling tools like ask_pipeworx (single lookup) and compare_entities (comparison). It specifies the resource (structured data sources) and the action (research/decompose/route).

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 when-to-use guidance: 'Best for broad/multi-part questions over structured data' with examples, and explicit when-not-to-use: 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', including the alternative tool name. Also states account requirements and fallback if not signed in.

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

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

Annotations already mark readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral details: returns top-N relevant tools with full input schemas and curated examples, ready to call directly. This goes beyond annotations and clarifies the output format.

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, each serving a clear purpose: (1) state what the tool does and list domains, (2) describe the return format and its readiness, (3) provide usage guidance. No wasted words; front-loaded with the core purpose.

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

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

Despite no output schema, the description thoroughly explains what is returned (tool names, descriptions, schemas with examples). It also addresses the high parameter count by listing aliases and explaining the main parameter's behavior. 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%, and the description adds meaning by explaining that 'query' accepts natural language and lists aliases (task, q, search, description). It clarifies the limit parameter's default and max. This adds significant value over the raw 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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and explains the return format (top-N tools with full schemas). This distinguishes it from sibling tools like deep_research or search_within, which serve different discovery needs.

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

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

Explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when to use it. However, it does not explicitly state when NOT to use it or list alternatives, leaving minor room for improvement.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. Description adds valuable behavioral context: fans out across multiple sources, notes patents soft-fail, requires ticker or CIK, and returns specific fields. 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 dense but efficient, front-loaded with example queries and preference statement. Every sentence adds value, though slightly long. Could be more concise but well-structured.

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

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

No output schema, so description explains return fields in detail. Covers core aspects (cik, filings, fundamentals, patents, news, LEI). Lacks mention of pagination or rate limits, but for a holistic profile tool it is fairly complete.

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

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

Schema coverage is 100%, but description adds meaning: type is only 'company' (refines enum), value must be ticker or zero-padded CIK, and names not supported. This goes beyond schema documentation.

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

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

The description clearly states it provides a full cross-source profile of a US public company, listing specific data sources (SEC, XBRL, USPTO, news, GLEIF) and output elements. Contrasts with chaining single-pack lookups, distinguishing it from siblings.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Provides example queries and warns about limitations (patents soft-fail, names not supported), giving clear when-to-use and when-not-to.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not reveal any new behavioral traits 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?

Three short sentences, no wasted words. Every sentence adds value: purpose, usage guidance, and pairing with siblings.

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 required parameter, no output schema, and no nested objects, the description is complete and sufficient given the complexity.

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 'key', with a description 'Memory key to delete'. The description adds no 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?

Clearly states 'Delete a previously stored memory by key'. Verb and resource are specific, and the description distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: stale context, task done, clearing sensitive data. Mentions pairing with remember and recall, but does not detail when not to use or alternatives beyond these.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds process details: fetches the page, extracts title/description/key links, and emits standard format. This goes beyond annotations by explaining the workflow and output format.

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: first states purpose and audience, second explains process, third lists use cases. No redundant words, front-loaded with key information. Every sentence earns its place.

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

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

Given no output schema, the description explicitly states output is a 'single text blob ready to drop at site-root/llms.txt'. Parameter count is low (2) with full schema coverage. The tool is simple and the description covers all necessary information for an agent to use it correctly.

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

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

Input schema covers 100% of parameters with descriptions. The description clarifies the overall purpose ('production-ready', 'standard format') but does not add significant new meaning to individual parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with specific mention of target AI crawlers. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on generating the standard llms.txt markdown document.

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 lists three explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor's AI crawler view. While it doesn't explicitly state when not to use it or name alternatives, the context is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying returned fields and default filtering to active subscriptions, enhancing transparency beyond annotations.

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

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

Two sentences with no wasted words. The purpose and return fields are front-loaded, followed by usage guidance. Extremely concise and well-structured.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context adequately. Missing details like pagination or rate limits, but acceptable given 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 description coverage is 100% for the one parameter. The description reiterates the parameter's effect ('include_inactive' for cancelled subscriptions) but does not add significant new meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions', specifying the verb 'list' and resource 'subscriptions' with scope. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use it. No explicit when-not or alternatives, but 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?

Annotations are all false, so the description carries the burden. It discloses the claim_token return process, the follow-up workflow to check status, rate limiting (5/day), that it is free, and that the team reads digests daily. This goes far beyond what annotations provide and gives the agent important operational 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?

Although the description is long, every sentence earns its place: scope, when-to-use, counter-example, claim_token mechanics, rate limit, and cost. The structure flows logically from what → when → what not → how to follow up. No redundant or filler content.

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

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

The tool has 4 optional parameters, no output schema, and a nested context object. The description fully covers purpose, scope, constraints, return behavior, and follow-up flow. Given the low complexity and rich description, there are no informational 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. The description adds meaningful context for the claim_token parameter (how to reuse it to read responses) and provides guidance for message content (specific, 1-2 sentences, 2000 char max). This lifts it above baseline but not to 5, as the schema already documents all parameters well.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This is a specific verb+resource phrasing that distinguishes it from sibling tools, which are mostly research/query tools. No ambiguity about what this tool does.

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

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

The description explicitly enumerates when to use the tool (bug, feature/data_gap, praise) and provides a clear exclusion rule: only for tools served by this Pipeworx connection, with a 'Not sure?' test. It also tells users to file with other servers for non-Pipeworx tools. This is excellent 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds caching behavior (5min-1h), data source (CF analytics-engine), and privacy (no PII). This provides additional context beyond annotations but doesn't cover all potential traits like rate limits.

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

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

The description is well-structured with numbered use cases and dashes for additional info. It is fairly concise for the amount of useful detail, though slightly longer than strictly necessary. No sentence is wasted.

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

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

Given the tool's simplicity (one optional enum parameter, no output schema), the description covers purpose, use cases, caching, and data origin. It does not explicitly state return format (likely a list/JSON), but that's minor given the 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?

The description adds meaning to the single 'window' parameter by explaining 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Since schema coverage is 100% and the description provides interpretive guidance, it adds value beyond the schema.

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

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

The description uses a specific verb+resource: 'returns top tools, top packs, and total call volume' clearly stating what the tool does. It distinguishes from siblings by focusing on aggregate trending data rather than specific queries or entity profiles.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case) which provide good context. However, it does not explicitly state when not to use this tool versus alternatives like discover_tools or search_within.

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 confirm read-only, idempotent, non-destructive behavior. Description adds extensive details: internal checks (monotonicity, partition_sum, semantic anchor, partition filter, fill check), output structure, and disclaimers about thin legs. No contradictions with annotations.

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

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

Description is long but well-structured, with clear sections for each mode and internal details. Front-loads main purpose and uses bullet-style explanations. Some redundancy (e.g., repeated mention of 'partition_check' specifics) but justified by complexity.

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

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

No output schema, so description fully documents response structure: 'opportunities[]' fields and 'partition_check' in event mode. Covers edge cases (skipped_low_similarity, partition filter, fill check) and provides actionable trading guidance. Highly complete for the tool's complexity.

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?

Input schema covers both parameters with descriptions (100% coverage). Description enhances by explaining parameter values ('event slug like "fed-decision-may-2026"'), providing examples, and clarifying behavior (e.g., 'Full Polymarket URLs also accepted'). Adds significant value beyond schema.

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

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

The description clearly identifies the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also advises against trading when 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?

The description discloses caching (1h at KV level), diagnostics so callers see why segments are empty, and detailed model behavior, including tradeable-edge knobs and 24h-move warning. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description adds rich behavioral context without contradiction.

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

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

The description is long but well-structured: purpose first, then segment details, tradeable-edge knobs, response top-level, and caching. Every sentence adds necessary detail for correct usage. While it could be slightly more concise, the thoroughness is justified by the tool's complexity (9 parameters, three models, diagnostic output).

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 complex behavioral details, the description is remarkably complete. It covers the three model families, all knobs with usage context, response structure including diagnostics, a Fed bets note, and caching policy. No obvious gaps remain for an agent to understand what the tool does and how to invoke it.

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 substantial value beyond schema: e.g., min_partition_leg_kelly explains why min_kelly doesn't filter partition arbs, max_spread_pp gives concrete guidance ('Set to 2 to require tight books'), and slippage_pp clarifies Polymarket's fee structure and practical bid/ask impact. Each parameter has explanatory text that aids agent decision-making.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific purpose of 'what should I bet on today'. It details three distinct response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like polymarket_arbitrage, polymarket_edge_tracker, and polymarket_fill_risk by focusing on discovery and ranking.

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 sets context: 'Built for what should I bet on today' and 'agents discover opportunities without paging hundreds of markets'. It also explains that Fed bets surface under fed_candidates but are excluded from ranking due to unreliable signal. However, it does not explicitly mention when not to use this tool or compare to siblings like polymarket_arbitrage (for specific arbitrage) or polymarket_edge_tracker (for tracking edges over time), which would strengthen 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 denote read-only, idempotent, non-destructive. Description adds context about snapshot gaps (cache-miss), negative edge_pp_net meaning, and 60-day TTL, enhancing transparency beyond annotations.

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

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

Front-loaded with purpose, then logically covers response fields and limitations. Slightly verbose but every sentence adds value; could trim some explanatory asides.

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 all response fields (tracked, expired, snapshot_dates) and limitations (TTL, gaps). Lacks a precise definition of edge_pp_net but covers key aspects.

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

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

Schema coverage is 100% with descriptions. The description adds defaults and clamp for 'days', meaning of 'window' families, and detailed response structure, providing added value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' built from daily snapshots, answering specific questions about edge duration and trend. It distinguishes from sibling 'polymarket_edges' by focusing on historical persistence.

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

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

Provides context on when to use (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'). Implies usage for historical trend analysis, but does not explicitly state when not to use or list 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: it walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), warns about forced directional risk and thin legs. No contradiction with annotations; description adds value beyond them.

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

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

The description is lengthy but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). Every sentence is informative, but some redundancy could be trimmed. Given the two-mode complexity, it's acceptable.

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 documents all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp for single-market; theoretical_sum, capture_ratio, thin_legs for basket). It also covers edge cases and risks, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: explains default for side in basket mode, clarifies size_usd interpretation (spend vs target proceeds for single-market, settlement notional for basket), and details market vs event modes. This goes 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool.

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

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

The description provides explicit guidance on when to use this tool: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or any polymarket_edges trade above ~$500. It explains why (theoretical overround not capturable, partial fills create directional risk), giving clear context for usage.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds rich behavioral traits: compatibility_warning conditions (non-equivalent bet shapes, semantic mismatch), temporal_alignment check, and skipped_cross_type/subtype counters. 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 front-loaded with purpose and structured into clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). While relatively long, each section earns its place by explaining complex behavior. Minor redundancy ('REAL cross-venue spreads are rarer...') prevents a perfect 5.

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

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

Despite no output schema, the description comprehensively explains the response structure (leg-by-leg prices, spread list, safety fields) and edge cases (compatibility_warning, temporal_alignment). It leaves no ambiguity about what the tool returns or fails gracefully.

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

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

The input schema has 100% coverage with clear descriptions for each parameter. The description explains the relationship between parameters (overrides) and modes, but this is largely redundant with schema descriptions. It adds narrative value but not new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses specific verbs ('compute spread'), identifies the resource (two prediction markets), and distinguishes itself from sibling tools like 'polymarket_arbitrage' which likely focuses on intra-venue arbitrage.

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 defines two modes (topic shortcuts and explicit tickers) and explains when to use each. It also provides a crucial caveat: 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' guiding the agent on realistic expectations and preventing misuse.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. The description adds behavioral context: scoping to identifier, listing behavior when omitting key, and pairing with other tools. 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?

Three concise sentences, each adding value. First sentence states primary function, second provides usage context, third mentions pairing. 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 retrieval tool with no output schema, the description fully explains behavior (single vs list), scoping, and relationship to sibling tools. Agent has sufficient information 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?

Input schema covers the only parameter 'key' with a clear description. The tool description restates that omitting key lists all keys, but adds minimal extra meaning beyond the schema. Schema coverage is 100%, so baseline 3 applies.

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

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

The description clearly states the tool retrieves a value or lists all keys, with specific verb ('retrieve', 'list') and resource ('value', 'keys'). It distinguishes from sibling tools 'remember' and 'forget' by naming them directly.

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: 'look up context the agent stored earlier... without re-deriving it from scratch'. Implicitly advises against using when save/delete are needed, and explicitly mentions pairing with 'remember' and 'forget'. Scoping is also clarified.

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?

Describes important behaviors beyond annotations: the mark_read parameter flags events as read, affecting future calls. Also notes the alternative REST endpoint. No contradiction with the readOnlyHint annotation.

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

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

Concise and well-structured: starts with the main purpose, details returned data, lists filter options, explains mark_read behavior, and ends with polling note and alternative. No unnecessary sentences.

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

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

Covers key aspects: what events contain, filtering options, side effects of mark_read, and alternative access. Lacks explicit mention of unread_only behavior, but schema covers it. Without output schema, the description provides sufficient context.

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

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

Schema coverage is 100%, and the description adds value by providing examples (e.g., 'sec_8k' for type) and explaining the purpose of mark_read. Some parameters like limit and unread_only are not elaborated in the description but schema covers them.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with specific verb and resource. It distinguishes from sibling tools like list_subscriptions and subscribe by focusing on alerts retrieval.

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

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

Provides context for usage: polling works fine, and the same feed is available via a REST endpoint for scripts. However, it does not explicitly compare against sibling tools or state when not to use this tool.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: fans out to multiple sources (SEC, GDELT, USPTO), fallback from GDELT to GNews, soft-fail for patents, structured return format, and citation URIs. This goes well 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 relatively long but front-loaded with example queries. Each sentence adds value (sources, fallback, parameter format, alternative tool). It could be slightly trimmed without losing information, but it remains 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?

Given three required parameters and no output schema, the description explains the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It covers source fallbacks, parameter options, and sibling differentiation. The tool's complexity (multiple data sources, failure modes) is well documented.

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 descriptions. The description adds extra clarification: explains `since` accepts ISO date or relative shorthand with examples, recommends '30d' or '1m', and notes `type` only supports 'company'. This adds meaningful guidance 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 starts with example queries like "What's new with X" and explicitly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It distinguishes from sibling tool `entity_profile` which is for static profiles.

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

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

The description clearly states when to use this tool vs `entity_profile`: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It does not provide explicit when-not-to-use scenarios, but the alternative is well-defined.

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

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

Discloses that data is stored as key-value pairs scoped by identifier, with persistence differences: authenticated persistent, anonymous 24 hours. Consistent with annotations (idempotentHint=true, not readOnly). Adds 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 front-loaded with purpose, then usage, then behavior. No redundant information. Efficient and easy to parse.

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

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

Covers purpose, usage, persistence behavior, and pairing with siblings. No output schema, but for a write tool this is acceptable. Could mention return value (e.g., success confirmation) but not essential.

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

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

Schema has 100% coverage with descriptions. Description adds example keys and clarifies value can be any text. Provides extra context like 'findings, addresses, preferences, notes' beyond schema's concise descriptions.

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

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

Clearly states the tool saves data for reuse across conversations or sessions. Gives concrete examples like resolved ticker, target address, user preference. Distinguishes from siblings 'recall' and 'forget' by mentioning 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?

Explicitly says when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget. Provides context on persistence for authenticated vs. anonymous users. Lacks explicit 'when not to use', but usage is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds valuable context: unresolved identifiers are explicitly listed under `unresolved` rather than omitted, and LEI/FIGI enrichment degrades gracefully if source APIs fail, still returning EDGAR identifiers. This gives the agent confidence about failure behavior and output completeness.

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

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

The description is long but densely packed with necessary information for a complex two-type entity resolution tool. It front-loads usage examples and purpose, then details supported types and failure behavior without redundancy. Some sentences are long, but every part adds functional value, so the length is justified.

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

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

Given the tool's multi-source lookup behavior and no output schema, the description fully covers what the agent needs: output format (labeled identifiers, unresolved list), supported entity types, input formats, enrichment fallback, and the fact that it replaces multiple manual lookups. This is comprehensive for an agent to correctly select and invoke the tool.

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

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

The input schema describes both parameters (type and value) with examples, giving 100% coverage. The description goes further by explaining that for 'company', value accepts ticker, CIK, ISIN, or name, and for 'drug' accepts brand or generic name. It also clarifies that ISIN resolves to the issuing legal entity via GLEIF mapping, enriching parameter 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 core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates the specific identifier types (ticker, CIK, LEI, RxCUI, FIGI) and provides illustrative query patterns. This distinguishes it from siblings like compare_entities and entity_profile by emphasizing it is the entry-point for name-to-ID resolution.

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: 'Use FIRST whenever you have a name but need an ID.' It also explains that each call internally cascades through multiple lookup endpoints, 'replaces 2-3 manual lookups,' and notes graceful degradation for enrichment services. This clearly tells the agent when to choose this tool over alternatives.

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

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

Annotations already declare safe/idempotent. Description adds that it probes each entity with ai_visibility_check and returns ranked results with metrics. No contradictions. Could mention rate limits or error handling.

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 that front-load purpose and behavior, then use case and output. Every sentence adds value.

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

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

Covers purpose, behavior, output format. Lacks explanation of confidence/signal density metrics but sufficient for agent to understand. No output schema, but description mitigates.

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 all 4 parameters with descriptions. Description adds extra meaning: first entity treated as 'subject', models default behavior explained. Adds value beyond schema.

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

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

Specific verb 'compare' and resource 'AI visibility across entities'. Clearly distinguishes from single-entity sibling ai_visibility_check and generic compare_entities. Explicitly states ranking and output.

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 case for competitive AI-marketing audits, but does not mention when not to use or explicitly list alternatives beyond implied distinction from single-entity probe.

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, idempotent, non-destructive. Description adds behavioral context beyond annotations: the composite nature, sources used, return structure (summary block, advisories, links, alternative versions), and failure handling (sources_failed if bundlephobia times out). 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?

Description is a single paragraph but front-loads the purpose and key details. It is dense but not overly verbose; every sentence serves a purpose. Could be slightly more structured with bullet points for readability.

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

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

Covers all essential aspects: composite nature, sources, return data fields, failure behavior, ecosystem limitation, and fallback guidance. No output schema, so description compensates well.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package, version). Description does not add new semantics beyond restating scoped package acceptance and default version behavior, so 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 starts with a clear composite purpose: 'should I add this npm package to my project' check. It specifies the verb (composite check) and resource (npm package dependency), and distinguishes from sibling tools by focusing on npm package analysis, which no other sibling explicitly targets.

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

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

Explicitly states when to use: 'when an agent asks is X safe / popular / small' and provides constraints: NPM ecosystem only, with alternatives listed for other ecosystems (deps.dev:version directly). Also mentions graceful degradation for bundlephobia delays.

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 the annotations: it specifies the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and input size cap (200K chars with truncation flag). These details are not present in the annotations and are crucial for correct usage.

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 well-structured paragraph. The main purpose is stated upfront, with every sentence adding essential information (use case, output, limitations, pairing). No redundant or verbose language.

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 explicitly mentions that returned passages include character offsets and similarity scores. It also covers input limits, truncation behavior, and relationship to a sibling tool. The description is complete and leaves no critical questions unanswered.

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 baseline is 3. The description enriches the parameter understanding by providing examples for the query parameter and clarifying the text parameter's character limit. This extra context justifies a 4.

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

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

The description clearly states that the tool performs semantic search inside a fetched record, giving concrete examples (SEC 10-K, article) and contrasting with using the whole document. It also hints at differentiation from sibling tools like ask_pipeworx_grounded.

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

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

The description explains when to use the tool (when the record is too big to fit in the prompt) and how it pairs with ask_pipeworx_grounded, but it does not explicitly state when not to use it or list alternative tools.

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

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

The description richly details behavioral traits: return value (subscription id), idempotent nature (implicit from creation), delivery channels with constraints (e.g., SMS 10/day cap, webhook auto-disable). These go well beyond the annotations, which only hint at idempotency and non-destructiveness. No contradictions with annotations.

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

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

The description is a single dense paragraph but front-loads the key action. It efficiently packs examples and constraints without being overly verbose. Could benefit from slight restructuring (e.g., bullet points for types) but is acceptably concise.

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

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

Given no output schema, the description mentions the return value (subscription id). It covers all parameter aspects, delivery options, and type details. It does not address error cases or idempotency behavior explicitly, but those are covered by annotations. Fairly complete for a creation 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?

With 100% schema coverage, the baseline is 3. The description adds significant value by giving concrete examples (e.g., items for sec_8k, topic for polymarket_edge) and clarifying delivery constraints (e.g., phone must be verified). However, it largely mirrors 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 verb 'Create' and the resource 'a proactive monitoring subscription to a live-data event stream'. It also mentions the return value (subscription id). The purpose is specific and distinguishes the tool 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 provides explicit prerequisites (Pipeworx OAuth account) and mentions constraints (anon/BYO not supported). It does not directly compare to siblings, but the context of subscription creation is clear. It could be improved by stating when to use this vs. list_subscriptions or unsubscribe.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining the tool returns dynamic example questions drawn from a live catalog, without contradicting any annotations.

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

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

The description is front-loaded with the purpose and includes a list of example natural language queries that make it clear how to invoke the tool. It is somewhat lengthy but every sentence adds value, and the structure is logical.

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 simple interface (one optional parameter, no output schema) and the annotations that cover safety and behavior, the description provides sufficient context about what the tool returns and when to use it. It explains the return format and the dynamic nature of the catalog.

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

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

Schema description coverage is 100% with a clear description for the topic parameter. The description adds extra value by explaining that omitting topic gives a full spread and providing example values, 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?

The description explicitly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions. It uses specific verbs and resources ('returns category-bucketed example questions... each with the exact tool + argument shape') and distinguishes from siblings by indicating it should be used first.

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

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

The description clearly states when to use the tool ('FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.') and how to call it (with or without the topic argument). It does not explicitly state when not to use it, but the context is sufficiently clear.

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

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

Adds details beyond annotations: ownership check, logical deactivation (not deletion), and preservation of historical events. Annotations already indicate idempotent and non-destructive, so description complements well.

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. All essential information is presented efficiently.

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

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

For a tool with one required param and no output schema, description covers purpose, ownership, side effects, and links to related tool ('recent_alerts'). Complete.

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

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

Schema coverage is 100% with clear description of 'id' parameter. Description does not add new meaning beyond what schema already provides for the parameter.

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

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

Clearly states 'Cancel a subscription by id.' with specific verb and resource. Distinguishes 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?

Provides context on ownership enforcement, implying when to use (own subscriptions). No explicit exclusions or alternatives, but sufficient for a simple tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the critical caller warning that could_not_verify means the check did not happen and must not be treated as evidence (with verification_error{stage,detail}), the difference between could_not_verify and unsupported, the verdict vocabulary, and the structured vs. grounded pipeline routing. It loses one point because it doesn't discuss rate limits, latency, or cost for the fallback grounded pipeline, which could affect agent decisions, but the core behavioral nuance is well disclosed.

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

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

The description is long but information-dense and front-loaded with trigger phrases. Every sentence earns its place: trigger examples, routing logic, verdict list, citation format, caller warning about could_not_verify, and replacement value proposition. It loses one point for being somewhat long and for the parenthetical list of verdicts being a bit heavy; a tighter version could trim the trigger-phrase list without losing meaning. Still, it is well-structured and avoids fluff.

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

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

Given the tool has no output schema, the description compensates fully by enumerating the exact verdict vocabulary, the citation format (pipeworx://), the reasoning inclusion, and the error-state semantics. For a 2-param tool with 100% schema coverage and readOnly/idempotent annotations, the description covers functionally everything an agent needs to select and invoke the tool, interpret results, and avoid misuse (could_not_verify warning). The only minor gap is cost/latency of the fallback pipeline, but that is not essential for correct invocation. This is a complete, production-grade description.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly: claim with natural-language examples, tolerance_pct with range, override semantics, and default behavior. The description adds value by explaining how tolerance_pct interacts with claim wording ("Overrides the tolerance implied by the claim wording") and by tying the claim parameter to the tool's overall routing logic. It doesn't add much beyond the schema, but the schema already carries the heavy lifting, so a 4 is fair (baseline 3 for full coverage, plus the added semantic framing of the tolerance override and claim verification pipeline).

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

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

The description starts with natural-language trigger phrases ("Is it true that…", "fact check", etc.) and states a specific verb+resource: 'natural-language claim verification against authoritative sources'. It clearly distinguishes from siblings like resolve_entity, search_within, compare_entities, and deep_research by naming its unique job (verify claims, return verdicts) and by explicitly noting it replaces 4–6 sequential calls. The scope is concrete (company-financial via SEC EDGAR/XBRL fast path; everything else falls through to grounded pipeline).

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 the agent needs to check whether something a user said is factually correct.' It also provides negative guidance by enumerating trigger examples and by distinguishing structured vs. unstructured fallback paths. Sibling differentiation is implicit through tool name ('validate_claim' vs 'resolve_entity' vs 'search_within') and explicit in the 'Replaces 4–6 sequential calls' note, which tells agents this is the consolidated alternative to a multi-step pipeline.

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