Schrodingers Boolean

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and nondestructive. The description adds behavioral context: probing multiple models, default free model, and the need for a key to enable Anthropic. No contradictions with annotations.

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

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

Two sentences that efficiently convey purpose, usage, return value, and key behavior. No wasted words; information is front-loaded and well-structured.

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

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

The description explains the return structure (per-model score, confidence, signals, raw_response, combined view) despite no output schema. It addresses the tool's complexity with optional models and API key, though it could be slightly more detailed on error conditions.

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 adequate descriptions for all four parameters. The description adds marginal value by explaining the default model for 'models' and the role of 'context' for disambiguation, but does not exceed the schema's own 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?

Description clearly states it probes LLMs about an entity and scores visibility (0-100) per model. It specifies the default model and distinguishes from sibling tools like scan_competitor_ai_presence by focusing on general brand awareness rather than competitive analysis.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and clarifies that Anthropic probing requires a BYO key. However, it does not explicitly contrast with siblings like compare_entities or scan_competitor_ai_presence, which could lead to ambiguity.

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 valuable behavioral context beyond the annotations: it routes to one of 5,462 tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. It also notes it works on every tier and is one fast call. While it does not discuss failure modes or rate limits, the annotations already cover safety characteristics, so the added routing and output details are sufficient.

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: it front-loads the critical 'PREFER OVER WEB SEARCH' directive, then categorizes use cases, provides examples, and concludes with escalation paths. Every sentence adds practical value, though some redundancy exists between the domain list and the trigger phrases. It earns a strong score for organization and utility.

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

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

This is a high-complexity routing tool with no output schema, yet the description covers the answer format (structured answer with citation URIs) and the operational context (default entry point, tier availability, speed). It also explains when to step up to other tools. Given the rich usage guidance and examples, the description is fully contextual and complete for agent decision-making.

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

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

The input schema covers all parameters with detailed descriptions and aliases, achieving 100% coverage, so the schema does the heavy lifting. The description does not explain parameter syntax beyond the schema, but it does clarify that the input is a natural-language question and gives examples. This meets the baseline but does not add substantial parameter-specific knowledge 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 role as a routing engine that dispatches factual questions to the appropriate internal tool and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point. The 'PREFER OVER WEB SEARCH' opener and explicit list of data domains make the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance including trigger phrases ('what is', 'look up', 'find', 'get the latest'), examples, and even 'even if web search could also answer it'. It names alternatives for specific scenarios: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This is strong conditional guidance that helps the agent decide between 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?

Annotates read-only, idempotent, and non-destructive, and the description adds meaningful behavioral nuance: being a beta with potentially active candidate changes, currently identical to stable, and results compared against the stable router. It also clarifies there is no fallback stub, fully disclosing the experimental edge.

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 four sentences that each carry useful information: definition, current status, usage guidance, and fallback clarification. It is slightly dense but well-structured and not wasteful.

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

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

The description explains the tool's role, beta status, and its relationship to ask_pipeworx, referencing the same response shape. No output schema exists, but the same response shape is acknowledged, which is sufficient given the sibling context. It could detail the response format, but overall coverage is good.

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 all parameters (question and five aliases). The tool description adds no parameter-specific meaning beyond that already in the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,462 tools, and distinguishes it from the stable version by highlighting candidate routing improvements. The purpose is specific and actionable.

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

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

Provides explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing.' It does not formally list when not to use or name all alternatives, but the stable ask_pipeworx is clearly implied as the alternative, and the experimental nature is stated.

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

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

Discloses significant behavioral traits beyond annotations: refusal reasons ('not_in_source', 'no_tool_match', etc.), evidence verbatim quoting, reliance on tool result only, and the extra LLM call cost. Annotations only indicate safe/read-only/idempotent, so description adds substantial value.

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

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

The description is dense but well-structured: starts with the key value proposition, then routing mechanics, then return format, then usage guidance and cost. Every sentence adds unique information, though it is longer than strictly minimal. Still appropriately front-loaded.

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

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

Despite no output schema, the description fully specifies the return shape on success and failure, including exact field names and possible refusal reasons. It also covers routing scope, evidence handling, and cost. Complete for a complex tool with high-stakes usage.

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

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

Schema coverage is 100% with full alias documentation, so the baseline is 3. The description adds no parameter-specific detail but does not need to; it focuses on behavior and use case, which is acceptable given the complete 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?

States a specific verb ('extracts the answer') and resource ('answer mode'), and explicitly distinguishes from sibling ask_pipeworx via 'Same routing as ask_pipeworx' with the added grounded-extraction behavior. Purpose is 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?

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), including the cost trade-off (extra LLM call). Provides clear guidance relative to the sibling tool.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: resolution steps, fan-out examples, response shapes, safety mechanisms (low-confidence resolution, closed markets, wide spreads), 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 comprehensive but verbose (~600 words). While well-organized with sections, it could be more concise for quick parsing. Every sentence adds value, but length reduces conciseness.

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

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

Despite no output schema, the description thoroughly covers response shapes, edge cases (low-confidence matches, closed markets, wide spreads), resolver contract details, and resolution-rule risk. It is complete for an AI agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning to 'market' (slug, URL, or question text), explains 'depth' options (quick/thorough), and specifies 'include_raw' default and use cases. This adds value beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + market vs model comparison), distinguishing it from sibling tools that focus on other aspects like arbitrage or edge tracking.

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

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

The description explicitly advises when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not list when not to use or name alternatives, the provided usage scenarios are clear and practical.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds key behavioral details: for company type it pulls financial data from SEC EDGAR/XBRL with off-calendar year handling, for drug type it pulls FAERS and FDA data. It also mentions results are sorted by primary metric and returns citation URIs. No contradiction with annotations.

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

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

The description is a single paragraph but effectively structured: starting with user query examples, then stating purpose, then detailing type-specific behavior. It's slightly long but every sentence adds value. Could be slightly more concise but still very good.

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 (two entity types, financial and drug data, sorting, citation URIs), the description covers essential aspects. It mentions return format (paired data + URIs) but doesn't detail exact output structure. However, annotations and schema compensate. A brief note on rate limits or pagination would improve completeness.

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 adds significant value: it provides example inputs (e.g., 'AAPL','MSFT'), explains what each type does, and clarifies constraints (2-5 values). This goes well beyond the schema's brief descriptions.

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

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

The description starts with explicit user queries ('Compare X and Y', 'X vs Y', 'which is bigger') and states the tool provides side-by-side comparison of 2-5 companies or drugs. It clearly distinguishes itself from sequential lookups by saying 'ALWAYS PREFER over sequential single-pack lookups'. The verb 'compare' and resource 'entities' are 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 to prefer this tool over sequential lookups when comparing entities. It also explains what each type returns (company vs drug). It doesn't explicitly state when not to use it, but the context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior; the description adds substantial context: account/depth requirements, parallel tool routing, expected latency, extraction semantics, gaps[] for unanswered facets, contradictions[] for conflicting findings, and citation fetchability guarantees. None of this contradicts the annotations.

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

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

The description is lengthy but dense and highly informative, covering prerequisites, use cases, behavioral details, and expected output. It is front-loaded with the account requirement and core purpose, though the single-paragraph format could benefit from clearer structural segmentation into sections (e.g., prerequisites, use cases, behavior).

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 thoroughly documents return values ('findings packet' with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field), performance expectations, and edge-case behavior (long document excerpting). This fully compensates for the absence of an output schema.

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

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

Schema coverage is 100%, but the description adds behavioral meaning to both parameters: depth is explained with quick/standard/thorough variants including hop counts and paid tiers, and question is clarified as supporting broad/multi-part input. This goes well beyond the raw enum and type definitions.

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

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

The description clearly states the tool performs 'grounded multi-source research' across Pipeworx's 1419 structured data sources, with explicit decomposition and parallel routing. It distinguishes itself from siblings like ask_pipeworx and open-web search, making the purpose unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: recommended for broad/multi-part questions, while single lookups should use ask_pipeworx, and breaking/current-news topics should also prefer ask_pipeworx. It also states account prerequisites and the fallback if not signed in, giving clear 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 readOnly and idempotent hints. The description adds valuable behavioral details: returns top-N tools with names, descriptions, full schemas, and curated examples, ready to call directly without a second lookup.

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, front-loading the core purpose and usage advice, then listing domains and return behavior. Every sentence adds value without redundancy.

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

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

Given the tool's purpose (discovery), the description covers all necessary aspects: what it does, when to use it, what it returns, and how to call it. No output schema is needed because the return format is described.

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

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

With 100% schema coverage, the description adds meaning by listing aliases for the query parameter (task, q, description, search) and providing example queries. This helps agents understand how to use the parameter flexibly.

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

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

The description clearly states the tool's purpose: to find/browse/discover tools by describing a task or data. It distinguishes itself from sibling tools by being a meta-search tool among many domain-specific tools.

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

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

The description explicitly advises calling this tool FIRST when many tools are available, providing clear context. It lists example domains but does not explicitly state when not to use it, though the guidance is strong.

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

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

The description adds significant behavioral context beyond annotations: it lists all data sources (SEC, XBRL, USPTO, news, GLEIF), what fields are returned, and notes that the USPTO component soft-fails due to an upcoming sunset. This aligns with annotations (readOnlyHint, idempotentHint) and provides transparency about partial failures.

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, front-loaded with examples and intent, and organized with a clear list of return fields. However, it is somewhat verbose (around 150 words) and includes some redundancy (e.g., mentioning name restriction twice), slightly reducing conciseness.

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

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

Given no output schema, the description fully specifies what is returned: CIK, name, filings up to 5 with URIs, fundamentals, patents with failure note, news, and LEI. Annotations cover safety. For a complex aggregation tool, this description is exceptionally 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%, so baseline is 3. The description repeats much of the schema's parameter info but adds slight context about the value parameter (ticker or CIK) and that type is limited to company. No 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 the tool's purpose: generating a full cross-source profile of a US public company in one call. It uses example queries and explicitly distinguishes itself from chaining individual lookups and from the sibling tool resolve_entity for name inputs.

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: when the user asks for a holistic view of a US public company. It also states to prefer it over chaining single-pack lookups, and specifies that names are not supported, recommending resolve_entity first.

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. Description adds minimal extra behavioral context ('clear sensitive data') but no further details on permissions or side effects. Since annotations cover the safety profile, a baseline score of 3 is appropriate.

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: one for purpose, one for usage context, one for related tools. No wasted words; all content 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?

For a simple tool with one parameter, clear annotations, and no output schema, the description fully covers purpose, use cases, and related tools. No gaps.

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

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

Schema coverage is 100% with description 'Memory key to delete'. Description does not add extra meaning beyond the schema, so baseline score of 3 applies.

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

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

Explicitly states 'Delete a previously stored memory by key' with a specific verb, resource, and method. Clearly distinguishes from sibling tools 'remember' (store) and 'recall' (retrieve).

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

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

Provides clear contexts for use: stale context, completed tasks, clearing sensitive data. Mentions pairing with related tools. Does not explicitly state when not to use, but the positive guidance is strong.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds process details (fetching, extracting, emitting markdown) without contradicting annotations. It could mention error handling or limitations, but the transparency is adequate.

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

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

The description is concise, front-loaded with the main purpose, and structured with a clear process and use case list. No unnecessary words 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 two simple parameters and no output schema, the description explains the input (URL, optional max_links) and output (markdown text blob) completely. The use cases provide full context for when to use this tool.

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

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

Schema describes both parameters fully with examples and defaults. The description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate given 100% coverage.

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 an llms.txt file for any URL, specifying the process (fetches, extracts, emits) and distinguishing it from siblings like scan_competitor_ai_presence by focusing on general URL indexing for AI crawlers.

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

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

The description explicitly lists use cases (client indexing, personal projects, competitor auditing), providing clear context. It does not explicitly mention when not to use or name alternatives, but the use cases are sufficient.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds value by listing specific return fields, consistent with annotations. No contradiction.

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

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

The description is concise: two sentences with no unnecessary words. First sentence states purpose and output, second gives usage guidance. Highly 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 the tool's simplicity, annotations cover safety, and the description covers purpose, return fields, and usage. No output schema needed. Slightly lacking in potential details like pagination but complete for a list 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 one boolean parameter. The description doesn't add further meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.), effectively distinguishing it 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 provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It doesn't state when not to use, but the context is clear enough.

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

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

Annotations are all false/empty, so the description carries full burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and processing cadence ('team reads digests daily'). It also warns against pasting end-user prompts, adding useful behavioral context.

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

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

The description is longer than typical but each sentence earns its place: purpose, use cases, exclusions, naming guidance, message format, and operational details. It is front-loaded with the core action and flows logically. Slightly verbose but not wasteful.

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 all necessary facets: what the tool does, when to use, scope restriction, rate limits, free/quotas, and message guidelines. It is fully sufficient for an agent to select and invoke this feedback tool correctly.

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

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

Schema describes all 3 parameters with 100% coverage, so baseline is 3. The description adds value by instructing how to frame the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which enhances the 'message' parameter semantics beyond schema. Does not add much for 'type' or 'context', but the boost is justified.

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

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

The description opens with a clear action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies the resource (Pipeworx team) and enumerates specific feedback types (bug, feature, data_gap, praise), making it distinct from sibling query/research tools.

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

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

Provides explicit when-to-use guidance ('Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog...') and a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' It also gives identification tips for unsure cases, which is superior 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, and not destructive. Description adds valuable context: data is aggregated from CF analytics-engine, no PII, cached 5min-1h. 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?

Concise at 5 sentences, front-loaded with main capability, structured bullet-like for uses. Every sentence provides unique 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers return structure, caching, privacy, and usage context. Completely adequate.

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 enum and description. Description adds meaning beyond schema: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps parameter selection.

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 it returns top tools, packs, and call volume over configurable windows. Distinguishes from sibling tools like 'discover_tools' by focusing on trending/popularity signals.

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

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

Lists three explicit use cases and explains window tradeoffs. Does not include negative guidance (when not to use), but use cases are clear enough to guide selection.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true, which match the description's non-destructive nature. The description adds significant behavioral context: semantic anchor (Jaccard similarity threshold), partition filter (placeholder detection), fill check (live CLOB depth analysis), and explicit 'do not trade' conditions.

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 verbose but all sentences contribute useful information about modes, filtering, and response structure. It is front-loaded with the main purpose and then systematically details each mode. The length is justified by the tool's complexity.

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

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

Despite having no output schema, the description thoroughly explains the response structure: opportunities[] with fields (gap_pp, suggested_trade, reasoning), partition_check details, and fill_check logic. It also mentions custom sizing with polymarket_fill_risk, covering all contextual needs for effective tool use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value beyond the schema by explaining event mode slugs/URLs, topic mode seed questions, and providing examples. This extra context justifies a score above baseline.

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

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

Description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', which is a specific verb+resource combination. It distinguishes from siblings like polymarket_edges and polymarket_fill_risk by detailing its unique method and modes.

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 explains when to call with no args (trending_scan), event mode (recommended for a specific market), and topic mode (cross-event scanning). Provides guidance on alternatives (e.g., polymarket_fill_risk for custom sizing) and includes examples.

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

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

Description goes far beyond annotations by detailing the three model families, edge calculations, caching behavior (1h KV-level), diagnostics for empty segments, and tradeable-edge knobs. All behavioral traits are disclosed transparently with no contradictions to 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 lengthy but well-structured with clear sectioning (key-value pairs, knobs, response structure). It front-loads the purpose and use case. Some technical details (e.g., exact alpha values) could be shortened, but the complexity warrants the length.

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

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

Given 9 params, no output schema, and no nested objects, the description comprehensively covers the response structure (by_segment, diagnostics, fed candidates), explains why segments may be empty, and describes caching. It leaves no significant gaps for an agent to use the tool effectively.

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 9 parameters are described in the schema, but the description adds significant semantic value by explaining the rationale behind defaults (e.g., slippage_pp, min_liquidity) and how parameters like min_partition_leg_kelly apply. This enriches the schema's descriptions without repeating 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?

Description clearly states the verb ('Scan'), resource ('Polymarket markets'), and outcome ('opportunities where Pipeworx data disagrees with market price'). It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx disagreement and from polymarket_edge_tracker by being a daily scan tool. The purpose is specific and unambiguous.

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

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

Description explicitly states the use case: 'what should I bet on today' and 'agents discover opportunities without paging hundreds of markets.' It provides context for when to use this tool vs alternatives, though it does not explicitly state when NOT to use it. Sibling names give implicit differentiation.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description details data source (daily snapshots, cache-miss triggers), limits (60-day TTL, snapshot start), and computation specifics (daily closes, not intraday). No contradictions.

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

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

The description is detailed but well-organized with bullet-style output sections (tracked[], expired[], snapshot_dates[]). It front-loads the key question. Slightly verbose but 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?

Given no output schema, the description fully explains the response structure and computed fields (trend, decay, first_seen, lifespan). It covers data limitations and interpretation details (signed values, negative meaning). Very complete.

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

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

Schema describes both parameters with 100% coverage. Description adds context: days default (14) and max (30), window options (24hr, 1wk, 1mo) and default (1wk). Slight mismatch in max (schema says clamp 2-30, description says max 30) but not misleading.

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 edge persistence and decay telemetry from daily snapshots, answering specific questions about edge duration and trend. It distinguishes from the sibling tool 'polymarket_edges' by adding time-series analysis.

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 the context of when to use it (comparing fresh vs. old edges) and implies an alternative (polymarket_edges for current state). It lacks explicit 'when not to use' or direct sibling comparisons, but the intent 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 indicate readOnlyHint=true, idempotentHint=true, etc. Description adds behavioral context beyond annotations: it walks the order book ladder, returns specific fields like slippage_pp and forced_directional_risk, and warns about thin books. No contradiction with annotations.

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

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

The description is long but well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Front-loaded with key purpose. Every sentence adds value given the tool's complexity. Could be slightly tighter but 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?

Despite no output schema, the description thoroughly covers return values (top_of_book, vwap_fill_price, slippage_pp, etc.) and risks. Addresses both modes, edge cases (thin_legs, forced_directional_risk), and usage context. 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 description coverage is 100%. The description adds significant meaning beyond schema: e.g., 'size_usd interpreted as settlement notional S (shares per leg)' for basket mode, and 'max spend on buys, target proceeds on sells.' Clarifies parameter behavior across modes.

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 it checks 'realizable-vs-theoretical edge against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, with specific verbs like 'walks the ladder' and 'returns.' It differentiates from siblings like polymarket_arbitrage and 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?

Explicitly requires one of `market` or `event`. Provides clear when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains risks of partial fills converting arb to unhedged position.

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

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

Beyond annotations (readOnlyHint, etc.), the description details the tool's behavior: it computes raw probabilities, spread, compatibility warnings, temporal alignment flags, and skipped cross types. It explains edge cases like matched_pairs=0 and non-equivalent bet shapes, offering deep transparency.

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

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

The description is relatively long but well-structured with clear sections and front-loaded key information. Every sentence adds value, though it could be slightly more concise. It earns a 4 for being informative without being wasteful.

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 (cross-venue, multiple modes, safety fields) and no output schema, the description thoroughly explains the response fields, warnings, temporal alignment, and skipped counters. It leaves little ambiguity, ensuring the agent can correctly interpret results.

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

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

Parameter descriptions in the schema already provide guidance (100% coverage), but the description adds further meaning: it lists all 10 topic shortcuts, provides examples for explicit tickers, and clarifies override behavior. This enriches the understanding 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 clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on the specific Kalshi-Polymarket pair and mentioning when bet shapes are equivalent or not.

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

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

It explicitly describes two modes (topic shortcuts and explicit tickers), provides a list of pre-mapped topics, and warns that real spreads are rarer than the list suggests, with compatibility warnings expected. This guides the agent on when to use and what to expect.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint false. The description adds context about scoping (to identifier) and the listing behavior when key omitted, which goes 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 filler. Front-loaded with primary action, followed by example use cases and relationships. 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?

Given the low complexity (one optional parameter, no output schema), the description fully explains the tool's behavior, scoping, and how it relates to sibling tools (remember, forget). No gaps.

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

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

Schema covers both usage cases with 100% coverage. Description reinforces and adds context: explains that omitting the key lists all saved keys, and that retrieval returns a specific value. This adds meaning 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?

Clearly states the verb ('retrieve') and resource ('value previously saved via remember'), and distinguishes from siblings by mentioning pairing with remember and forget. Also explains the dual behavior when key is omitted.

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 describes when to use ('look up context stored earlier') and how to use (omit key to list all). Also mentions scoping and pairing. Does not explicitly state when not to use, but the context is clear enough.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds behavioral details: each alert carries source, citation_uri, and raw payload; setting mark_read=true flags events as read for subsequent calls. This enriches transparency.

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

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

The description is four sentences, each purposeful. It front-loads the core purpose, then layers details in a logical order. No redundant or extraneous content.

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

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

Despite no output schema, the description hints at return structure (source, citation_uri, payload). It covers all parameters implicitly or explicitly, and mentions polling suitability. Adequately complete for a read-only, non-destructive 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 baseline is 3. The description adds value by providing examples ('e.g. "sec_8k"') and clarifying the effect of mark_read ('so the next call only shows newer ones'), going 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: 'Pull fired events from your subscription feed.' It specifies the resource (recent alerts from a persisted feed) and differentiates it from sibling tools like 'list_subscriptions' and 'subscribe' which manage subscriptions, not alerts.

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

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

The description provides context on when to use: 'Polls work fine' and offers an alternative (GET endpoint) for scripts/dashboards. It does not explicitly state when not to use this tool vs alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds critical behavioral details: parallel call to three sources, fallback logic, return structure (changes[], total_changes, citation URIs), and parameter format examples. 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 example queries and efficiently covers sources, parameters, and sibling differentiation. Though a bit lengthy, every sentence adds value. Minor redundancy could be trimmed.

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 3 params with 100% schema coverage, no output schema, and comprehensive annotations, the description fully explains the tool's behavior: sources, fallback, return structure, and parameter formats. It leaves no ambiguity for an AI agent to misuse 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%, so parameters are already documented. The description enhances this by providing practical usage examples for 'since' (ISO or relative, suggests '30d'/'1m'), clarifying 'value' accepts ticker or CIK, and noting 'type' only supports 'company'.

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

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

The description uses specific verbs ('fans out to SEC EDGAR, GDELT→GNews, USPTO') and resources ('change feed for a company'), and clearly distinguishes from sibling tool 'entity_profile' by stating its alternative use case.

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

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

The description provides explicit query examples (e.g., 'What's new with X', 'latest on Y') and tells when to use 'entity_profile' instead. It also explains fallback behavior (GDELT→GNews) and limitations (USPTO soft-fail).

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

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

Description adds details about scope, persistence across sessions, and 24-hour retention for anonymous users, complementing annotations that indicate idempotency and non-destructiveness.

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?

Single paragraph front-loads purpose, then usage, then behavioral details; slightly verbose but every sentence is useful.

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?

All necessary context provided for a simple store tool: purpose, usage, parameter hints, persistence behavior, and pairing with related tools. No output schema needed.

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 parameters are self-explanatory; description provides examples but no additional semantics 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?

Description clearly states 'Save data the agent will need to reuse later' with specific verb and resource, and distinguishes from sibling tools recall and forget.

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

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

Explicitly describes when to use (discover worth carrying forward) and alternatives (pair with recall/forget).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context beyond annotations: internal cascading through lookup endpoints, auto-disambiguation of inputs, and the return of citation URIs. This gives the agent a richer behavioral model without contradicting the annotations.

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

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

The description is well-structured and front-loaded with example queries and a clear directive. Although it is detailed, every sentence contributes distinct, useful information—supported types, return values, citation URIs, and internal behavior. It avoids redundancy and 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 there is no output schema, the description fully carries the burden of explaining return values. It does so comprehensively for both entity types, listing exact fields and citation URI formats. It also explains internal behavior and how the tool fits into a multi-step lookup workflow, making it self-sufficient for an agent.

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

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

Schema description coverage is 100% and both parameters are fully described. The description adds value by explaining what each type returns (e.g., ticker + CIK + company_name for company, RxCUI + ingredient + brand for drug) and clarifies the input flexibility (ticker/CIK/name for company, brand/generic for drug). This goes beyond the schema's parameter descriptions.

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

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

The description opens with concrete example queries and explicitly states the tool resolves a user-spoken name to the canonical/official identifier other tools require as input. It details supported types and their specific outputs (ticker+CIK for company, RxCUI+ingredient for drug), clearly distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

Provides direct usage instruction: 'Use FIRST whenever you have a name but need an ID.' It also notes the tool replaces 2-3 manual lookups, making the intended context clear. Though it does not list exclusions, the guidance is explicit 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 read-only, idempotent, and non-destructive behavior. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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 three sentences with no wasted words. It front-loads the purpose, then details mechanism 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?

Despite lacking an output schema, the description adequately describes the output format (ranked list with score, confidence, signal density) and the sub-tool used. For a tool with 4 parameters and moderate complexity, it is sufficiently 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?

Input schema has 100% coverage, so baseline is 3. The description adds semantic value beyond schema: it explains that the first entity in the array is treated as the 'subject' for narrative, and it clarifies the default model and requirement for 'anthropic' model.

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

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

The description uses specific verbs ('Compare', 'probes', 'ranks') and names the resource ('AI visibility'). It clearly distinguishes from sibling tool 'ai_visibility_check' by indicating multiple entities and side-by-side comparison.

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 a concrete use case ('competitive AI-marketing audits') and implies when to use (comparing multiple entities) versus using 'ai_visibility_check' for a single entity. It does not explicitly state when not to use but gives sufficient context.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds critical details beyond: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. 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 dense single paragraph but contains no filler. Every sentence adds value, though it could benefit from bullet points for readability. However, it remains clear 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?

For a composite tool with 2 parameters and no output schema, the description fully explains inputs, behavior (about alternatives and fallbacks), and output structure (summary block, per-advisory detail, links, alternatives). Partial failure handling is clearly described.

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% (both parameters described). Description adds value by explaining that 'version' defaults to latest and that scoped packages are accepted, providing extra context beyond the schema.

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

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

The description uses specific verbs ('composite check', 'fans out') and clearly states the resource (npm package) and the question the tool answers. It distinguishes from sibling tools by explicitly limiting ecosystem to NPM v1 and mentioning fallback for others.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clearly excludes non-NPM ecosystems, directing to alternative tool deps.dev:version.

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, and idempotentHint, so the description does not need to restate safety. The description adds context about the quantum superposition response and cat mode, and the 'reopen' parameter description warns it will fail, which is a behavioral hint 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 and front-loaded: two sentences that cover the core purpose, special modes, and return content. Every sentence adds value without redundancy.

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

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

Given that an output schema exists and annotations are rich, the description is adequately complete. It explains the core functionality and special features. It could be more detailed about when to use 'observe' or 'interpret' parameters, but these are covered in the schema.

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

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

The input schema has 100% description coverage for all parameters, so the description does not need to add much. It mentions 'cat mode' but does not elaborate on parameter syntax or semantics 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's function: ask a yes/no question and receive a quantum superposition answer. It also highlights special features (cat mode, wave function interpretation). The tool's unique whimsical nature distinguishes it from sibling tools, which are more conventional research and prediction tools.

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

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

The description implies usage for yes/no questions, but it does not provide explicit guidance on when to use this tool versus alternatives. There is no mention of when not to use it or prerequisites, though the sibling list lacks similar tools, reducing the need for differentiation.

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

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

The description discloses technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag, and that passages include character offsets for verification. There is no contradiction with annotations.

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

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

The description is front-loaded with the main purpose, then usage guidance, then technical details. Each sentence serves a purpose, though it could be slightly more concise. Overall 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?

Even without an output schema, the description explains return format: top-N passages with character offsets and similarity scores. It also covers input constraints (200K chars), use cases, and behavior on truncation. This is complete for an agent.

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

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

Schema description coverage is 100%, so the description adds limited value. It restates the max char limit for 'text' and clarifies that 'query' should be a natural-language query. While helpful, this aligns with the baseline score for high coverage.

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 performs semantic search inside a fetched record, specifying it's for large texts that can't fit in the prompt. It distinguishes from sibling tools like ask_pipeworx_grounded by noting they can be paired together.

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

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

Explicitly tells when to use ('Use when the record is too big to cram into the prompt') and provides an alternative workflow: fetch with the gateway, then use ask_pipeworx_grounded over the passages. This clearly guides the agent on when to invoke this tool 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?

Discloses that subscription persists, requires OAuth, and returns an id. Also notes webhook secret is returned once. Annotations already indicate idempotent and open world; description adds concrete behavioral details 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?

Front-loaded with purpose and key requirements. While lengthy, every sentence provides useful context. Could be slightly more concise but 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 complexity (nested params, multiple types, no output schema), description covers authentication, type-specific params, delivery options, and limitations. Missing return format beyond 'id' but acceptable.

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 value by providing concrete examples (e.g., items:['5.02']) and clarifying constraints (e.g., sponsor or condition required for clinical_trial). Exceeds baseline of 3.

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

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

Description clearly states the verb ('Create') and resource ('proactive monitoring subscription to a live-data event stream'), and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Explicitly states requirement of Pipeworx OAuth account, and mentions limitations (e.g., SMS 10/day cap, phone verification). Implicitly clarifies when not to use (anonymous/BYO cannot persist). Strong guidance but no direct 'when not to use' for each alternative.

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, etc. Description adds that output includes 'exact tool + argument shape' from live catalog, and that tool is idempotent. 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 focused and front-loaded with purpose and synonyms. Slightly long but retains value in every sentence; well-structured with dashes for grouping.

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 1 optional parameter and no output schema, description fully explains output (category-bucketed example questions with tool+argument shape) and usage context. No gaps.

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

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

Schema covers the single optional topic parameter with description. Description adds value by listing example topics and explaining behavior of omitting vs. providing topic. Baseline 3 from 100% schema coverage, plus extra explanation.

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

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

Description clearly states the tool returns category-bucketed example questions with exact tool + argument shapes. Distinguishes itself as the onboarding entry point, contrasting with sibling tools like ask_pipeworx, entity_profile, etc.

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 instructs to use this tool first when the agent doesn't know what Pipeworx can do. Provides guidance on arguments (omit for full spread, pass topic to focus) and mentions meta-tools to learn about.

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 the row is deactivated (not deleted) and historical events remain via recent_alerts. Consistent with idempotentHint and adds value 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 front-loaded sentences convey purpose, constraint, and side-effect without wasted words.

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

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

No output schema, but description fully covers behavior and side effects for a simple tool. Enough for correct invocation.

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

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

Schema covers 100% of parameters. Description clarifies that 'id' is the subscription id returned by subscribe, adding context 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?

Clear verb ('Cancel') and resource ('subscription') with specific identifier ('by id'). Distinct 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?

Explicit ownership constraint ('you can only cancel your own subscriptions') guides proper usage, though no direct comparison to alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail: returns a verdict (confirmed, refuted, etc.), provides grounded or structured actual value with citation, and explains the dual-path processing logic. No contradictions.

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

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

The description is concise but packs valuable information. It front-loads with example triggers and clearly separates the two processing paths. Slightly dense but not overly verbose—every sentence contributes meaning.

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

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

Given that there is no output schema, the description adequately explains the return values (verdict, actual value, citation, reasoning). It covers the core functionality and internal routing. However, it lacks details on error handling, rate limits, or edge cases like ambiguous claims.

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% (both parameters documented). The description adds value by explaining that tolerance_pct overrides the implied tolerance and suggests usage for hallucination detection (e.g., 'set 1–2 for hallucination detection'). This provides practical 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 clearly states the tool's purpose: verifying factual claims using natural language. It provides concrete example triggers and mentions it replaces 4-6 sequential calls, distinguishing it from sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes two processing paths (SEC EDGAR for company-financial claims, grounded pipeline for others). While it lacks when-not-to-use or alternative tool references, the context is clear enough.

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