Box

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable context: default free model, BYO API key with direct billing to Anthropic, and the return shape (per-model {score, confidence, signals, raw_response} + combined view). This goes beyond the structured hints without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value: what it does, cost/model details, and return/use cases. No waste.

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

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

Given no output schema, the description explains the return shape and covers inputs, cost, and use cases. The tool's complexity is low (4 params, 1 required), and the description provides sufficient context for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema documents all parameters well. The description adds cost semantics for _apiKey (you pay Anthropic directly) and clarifies the default model behavior, which adds meaning 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 clearly states the tool probes LLMs for knowledge about an entity and produces a 0-100 visibility score per model. It specifies the resource (business/brand/product/topic) and the verb (probe/score), distinguishing it from sibling tools like ask_pipeworx (which likely queries Pipeworx data) and scan_competitor_ai_presence.

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

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

Explicit use cases are provided ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use the tool. It does not explicitly name alternatives or exclusion criteria, but the use-case framing offers sufficient guidance.

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

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

Annotations already mark the tool as readOnly and idempotent. The description adds useful context: it routes to 5,439 tools across 1,412 sources, fills arguments, returns structured answers with pipeworx:// citation URIs, and works on every tier. It does not deeply discuss failure modes or response shape, but the extra context goes beyond the annotations.

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

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

The description is longer than necessary but front-loads the key directive ('PREFER OVER WEB SEARCH') and contains dense, useful information: categories, examples, alternatives, and behavior. Every sentence contributes, though the list of data categories and example queries could be trimmed without losing 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 tool's broad scope and lack of an output schema, the description is remarkably complete. It tells the agent what the tool does, when to use it, when to use alternatives, what inputs to provide, and what kind of output to expect (structured answer with citation URIs). This enables correct selection and invocation.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description reinforces that the question is natural language and gives examples, but it does not add substantial parameter-level semantics beyond what the schema already states.

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

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

The description explicitly states the tool answers factual questions about real-world data using structured sources and returns citations. It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as step-up alternatives.

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

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

The description gives strong when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE', and concrete alternatives for specific cases (grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It also provides examples of appropriate queries.

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, so the safety profile is covered. The description adds behavioral context beyond annotations by explaining the beta status, that no candidate routing is currently active, and that it currently matches ask_pipeworx exactly while being a full working router. This provides transparency about experimental nature without contradicting annotations.

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

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

The description is three sentences, each earning its place: it states identity, current state (no active candidate), and usage guidance. It front-loads the core fact that it is a beta version and avoids redundancy while providing necessary detail. No wasted words.

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

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

Given the tool's complexity as a universal router with no output schema, the description provides enough context: it matches ask_pipeworx, has the same response shape, and is fully functional. It does not detail what the router does internally, but referencing ask_pipeworx and stating 'same response shape' is sufficient for an agent to understand expected behavior.

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

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

Schema description coverage is 100%, with all six parameters being aliases for the required 'question' parameter. The schema already explains that question accepts natural language and lists the aliases. The description mentions 'same arguments' as ask_pipeworx, adding minor context but not needed for parameter understanding. 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 that ask_pipeworx_beta is a beta version of ask_pipeworx, an identical universal router with the same 5,439 tools, arguments, and response shape. It distinguishes from siblings by explicitly mentioning it is the experimental edge with candidate routing improvements. This gives a specific verb (ask) and resource (router) while differentiating from the stable and grounded variants.

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

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

The description provides clear usage context: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This tells the agent when to choose this tool over alternatives, though it does not explicitly list exclusions or when-not-to-use scenarios, which prevents a 5.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description discloses key behaviors: it routes like ask_pipeworx, extracts answers only from tool results, returns a specific structured response, and gives explicit refusal reasons. It also mentions the extra LLM call cost, adding valuable non-obvious 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?

While longer than typical descriptions, every sentence earns its place: purpose, routing behavior, output format, refusal reasons, use cases, and cost trade-off are all packed into a well-structured paragraph. Front-loaded with the core concept.

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 fully explains return values and refusal modes. It covers routing, extraction strictness, cost implications, and use cases, making it self-sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with all parameters being aliases for 'question', and the schema clearly documents each alias. The description adds no additional parameter semantics beyond restating the natural language question concept, so baseline 3 is appropriate.

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

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

The description clearly states this is a hallucination-resistant answer mode for high-stakes reads, using specific verb and resource. It distinguishes from sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior, making the tool's unique role unmistakable.

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

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

Explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). Also notes it costs an extra LLM call, providing practical selection guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond annotations: resolver confidence levels (high/medium/low/none), low-confidence short-circuit behavior, market_closed_or_inactive status, illiquid_wide_spread warnings, parent-event extraction, news fallback behavior, and cancellation-rule risk. No contradiction with annotations.

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

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

The description is long but exceptionally well-structured with clear section labels (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and a front-loaded one-sentence summary. Every section contributes functional knowledge, so the length is justified. However, it is dense enough that conciseness suffers slightly, preventing a 5.

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

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

With no output schema, the description carries the full burden of explaining return shapes, and it does so comprehensively: result.market, result.analysis, result.evidence, resolver contract fields, parent_event structure, news fallback fields, and edge-case statuses. It also covers safety precautions and cancellation-rule risk. This is a complete specification for a complex tool.

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

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

The input schema already provides 100% coverage with detailed descriptions for all three parameters (market, depth, include_raw). The description adds some context about the market input formats (slug, URL, question text) and mentions depth/raw in passing, but it does not meaningfully elaborate beyond the schema's own parameter documentation. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the tool's scope (resolving, classifying, fanning out, returning evidence) and explicitly lists three use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which distinguishes it from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

The description explicitly states when to use the tool with concrete example queries and gives detailed fan-out examples for various bet categories. However, it does not explicitly name alternatives or state when not to use this tool in favor of a sibling, so it lacks the exclusionary guidance that would push it to a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral detail by enumerating the exact return fields (id, name, size, description, timestamps, parent folder, shared link URL, extension), which helps the agent anticipate the tool's output without needing an output schema.

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 compact: two sentences that front-load the action and resource, then list return fields and usage context. There is no fluff or redundancy, every word 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 one-parameter tool with rich annotations and a complete schema, the description is fully adequate. It explains what the tool does, when to use it, and what output to expect, leaving no critical gaps for the agent to make a 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?

The schema description for file_id ('The Box file id of the file to inspect') is clear and complete, achieving 100% coverage. The main description adds only a slight clarification that the file is a single Box file. Since the schema already documents the parameter, the description provides minimal additional semantic value, warranting the baseline score of 3.

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

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

The description clearly states the tool's function: 'Get full metadata for a single Box (cloud storage) file by its file id.' This specific verb+resource combination distinguishes it from siblings like box_get_file_text (content extraction) and box_list_folder (multiple files). The scope is explicitly limited to a single file via ID.

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

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

It provides explicit usage context: 'Use after listing or searching to inspect one document.' This tells the agent when to invoke the tool without listing alternatives. While it doesn't explicitly name exclusions, the context (e.g., after listing/searching) and the sibling names make the differentiation 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 provide safety traits (read-only, idempotent, non-destructive, open-world). The description adds valuable behavioral details beyond that: binary files return 'unreadable bytes', content is capped at ~100,000 characters, and truncation is flagged. This goes beyond the structured annotations.

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

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

The description is two sentences that lead with the core action and then cover boundary conditions (binary formats, truncation) without wasted words. Every sentence adds value, and the structure is easy to parse.

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

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

This is a simple single-parameter tool with strong annotations and a complete schema. The description covers scope, limitations, and truncation behavior, making it fully adequate for an agent to use correctly without an output schema or more complex context.

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

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

The input schema fully documents the only parameter (`file_id`) with a clear description, so schema coverage is 100%. The tool description barely adds additional meaning beyond restating 'by its file id', which meets the baseline but does not elevate it.

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

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

The description uses a specific verb-resource pair ('Download and return the text content of a Box file') and clearly identifies the input required (file id). It also distinguishes itself from the sibling `box_get_file` by focusing on text extraction and noting binary file limitations.

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

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

The description explicitly states the ideal use case ('Best for plain-text, Markdown, CSV, and other text documents') and warns against binary formats, which is clear when-to-use guidance. It does not name an alternative tool directly, but the context is sufficient for an agent to choose appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds value by specifying the exact output fields and that storage amounts are in bytes, providing expectations 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 exactly two sentences: the first states the action and output, the second gives practical use cases. There is no extraneous information, and the most important information is front-loaded.

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

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

With no parameters, a detailed output schema is absent, but the description compensates by listing the return fields and units. Combined with forceful annotations and simple scope, the tool is sufficiently contextualized 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?

The input schema has zero parameters, so there is nothing for the description to explain. The baseline score of 4 applies, and the description confirms the tool takes no input by not mentioning any arguments.

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

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

The description uses the specific verb 'Get' with the resource 'the signed-in Box user's profile' and enumerates exact fields (id, name, login email, storage space). This distinguishes it from sibling tools like box_get_file and box_list_folder, making the tool's purpose unambiguous.

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

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

The description explicitly suggests two use cases: 'identify the connected account' and 'report storage usage.' While it does not mention when not to use this tool or name alternatives, the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond annotations by specifying the return fields: "Returns each item's id, type (file or folder), name, size in bytes, and last-modified time." It also clarifies the default behavior for omitted folder_id, which aids the agent in anticipating output.

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

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

The description is concise (three sentences) and front-loaded. The first sentence states the core action, the second explains parameter usage, and the third provides a use case. No wasted words.

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

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

For a simple, read-only list tool with two well-described parameters and no output schema, the description covers everything needed: purpose, parameter behavior, return format, and usage context. Annotations cover safety, so the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for both parameters (folder_id and limit), so the schema already documents their meanings. The description reinforces folder_id semantics with "Pass a folder id, or omit it to list the root folder ('0')" but adds little new information beyond the schema, warranting the baseline score.

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: "List the files and subfolders inside a Box (enterprise cloud storage) folder." It also specifies the scope (folder id or root) and distinguishes it from sibling tools like box_get_file or box_search by focusing on browsing folder contents.

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

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

The description provides clear usage context: "Use to browse a user's Box documents and files." It doesn't explicitly name alternatives or exclusions, but the read-only browsing purpose is evident, and the sibling tool names suggest distinctions (e.g., box_get_file for retrieving a specific file).

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

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

Annotations already declare this as read-only, idempotent, and open-world. The description adds value by disclosing that it searches both names and content, and by specifying the return fields (id, type, name, size, and last-modified time), which annotations do not cover. It does not contradict 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 two sentences long, front-loaded with the core purpose, and every sentence adds value: purpose, optional filter, return fields, and usage. No redundant or filler content.

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

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

Despite having no output schema, the description covers the essential return fields. It also mentions the optional type filter and the search scope (names and content), which together provide a complete picture for a search tool. The default limit is in the schema, so it doesn't need to be repeated.

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 parameters are fully documented. The description adds little beyond restating the type filter ('Optionally restrict to only files or only folders') and does not provide additional semantics for query or limit beyond what the schema already states.

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: 'Search a user's Box (cloud storage) account for files and folders matching a query string across names and content.' It uses a specific verb (search), specifies the resource (Box account), and distinguishes it from sibling tools like box_list_folder and box_get_file by emphasizing keyword search across names and content.

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

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

The description provides clear usage context with 'Use to find documents by keyword,' which implies the intended scenario for this tool. However, it does not explicitly mention alternatives or when NOT to use it, falling short of a 5.

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

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

Annotations already declare readOnlyHint and destructiveHint, reducing the burden, but the description goes beyond them by disclosing specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the return of paired data plus citation URIs. This adds significant behavioral detail without contradicting any annotations.

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

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

The description is dense but well-structured, starting with trigger phrases and then detailing behavior by type. Every sentence contributes useful information, though the 'Replaces 8–15 sequential lookups' line is somewhat promotional and the examples could be trimmed without losing clarity.

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

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

Given no output schema, the description compensates well by explaining what data is returned, how results are sorted, and that citations are included. It covers both entity types, parameter constraints, and the key advantage of parallel execution, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so parameters are already documented, but the description adds meaningful semantics by explaining what each type actually retrieves (company: 10-K financials; drug: FAERS counts, FDA approvals, trials). This goes beyond the schema's enum labels and enriches parameter understanding.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, with explicit trigger phrases like 'X vs Y' and 'rank these companies.' It also differentiates itself from sequential single-entity lookups, making its purpose unambiguous and distinct from sibling tools such as entity_profile.

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

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

The description explicitly says to 'ALWAYS PREFER' this tool when comparing entities, and provides clear context for when to use it (comparing companies/drugs). However, it doesn't name alternative sibling tools or state explicit when-not-to-use conditions, so it stops short of a full usage guide.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent) by detailing authentication needs (free sign-in, paid thorough), latency expectations (15-60s, up to 90s), output packet structure (gaps[], contradictions[], hop field), semantic excerpting behavior, and the 'never invented' guarantee. 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 front-loaded with the most critical decision-relevant information (account requirement, alternative tool). It is logically structured with examples and clear distinctions, though it repeats some details (e.g., NOT open-web search, citation format) and could be tightened by removing redundancy.

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

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

With no output schema, the description thoroughly explains the return format (findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]) and behavioral specifics for each depth tier. It covers authentication, latency, exceptions, and limitations, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it specifies that depth:'thorough' requires a paid plan, provides example question types, and clarifies that 'quick' is single-hop while standard/thorough include recovery hops. These enrich the parameter semantics beyond the schema's enum 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 performs grounded multi-source research across 1,412 structured data sources in one call, explicitly distinguishing it from open-web search and sibling ask_pipeworx. It specifies the resource (structured data sources) and the action (decomposes, routes, returns findings packet), making its purpose unmistakable.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part structured-data questions; single lookups should use ask_pipeworx; breaking/current-news topics should prefer ask_pipeworx because deep_research returns empty gaps. Also addresses account requirements and the fallback to ask_pipeworx if not signed in, giving clear alternatives and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are 'ready to call directly, no second schema lookup needed.' These details go beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the main purpose. The list of domains is long but serves as useful examples for the query parameter. It is not overly verbose and each sentence earns its place, though the domain list could be trimmed for 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 its moderate complexity (6 parameters, many aliases) and no output schema, the description covers essential aspects: what it does, when to use it, what it returns, and that results include schemas. It lacks explicit limitations (e.g., max limit 50) but the schema covers that. Overall, it is sufficiently complete for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning by listing example domains (e.g., 'SEC filings, financials, revenue, profit') that a user might include in the query. It also clarifies the 'top-N' behavior, which relates to the 'limit' parameter, adding semantic value beyond pure schema facts.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.), making it unambiguous. It also distinguishes itself from siblings by positioning itself as a discovery tool: 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies a use case (option set exploration) but does not explicitly state when not to use it or name alternatives, hence a 4.

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, but the description adds substantial behavioral context: fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), patent API sunset soft-fail, GDELT→GNews fallback, and specific return structure with sort order. These details go beyond what annotations provide and help set expectations.

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

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

The description is dense and front-loaded with examples and usage guidance, but the long list of seven query paraphrases could be seen as redundant. Still, each sentence contributes value—usage rules, source fan-out, return fields, and limitations—so it is concise enough for the tool's complexity.

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

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

With no output schema, the description thoroughly enumerates the return payload: cik/company_name, recent_filings with URIs, fundamentals (LATEST 10-K fields, sorted), patents with sunset status, news fallback, and LEI. It also mentions limitations and prerequisite actions, making it highly complete for a multi-source, 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% and the schema already explains value as ticker or zero-padded CIK, and names not supported. The description repeats this without adding new parameter semantics, only giving query examples. 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 states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call,' with explicit query examples. It clearly distinguishes from sibling tools by warning against chaining single-pack lookups and referencing resolve_entity for name-based lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives an exclusion: names are not supported—'use resolve_entity first if you only have a name.' This effectively differentiates from 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 destructiveHint=true and idempotentHint=true, so the safety profile is clear. The description adds minimal behavioral context ('by key', 'previously stored') but does not elaborate on side effects or permanence, which the annotations sufficiently cover.

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

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

The description is two sentences: the first states the core action, the second gives usage guidance and related tools. No filler or redundant information exists, making it 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?

For a simple destructive tool with one parameter and no output schema, the description fully covers purpose, usage timing, and integration with sibling tools. Annotations handle safety concerns, so nothing essential is missing.

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

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

The schema fully documents the single 'key' parameter with 'Memory key to delete.' The main description repeats 'by key' without adding new semantics. With 100% schema coverage, no additional parameter information is needed.

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 action: 'Delete a previously stored memory by key.' This distinguishes it from sibling tools like remember (store) and recall (retrieve), making the tool's function 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?

It explicitly provides use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools to pair with, offering clear guidance on when to invoke this tool.

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

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

Annotations already disclose read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful process context: it fetches the page, extracts title/description/key links, emits standard markdown, and returns a text blob ready for site-root placement. 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 three sentences long, front-loaded with the primary purpose, and every sentence adds value: what it does, how it works, and when to use it. No filler or redundancy.

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

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

For a tool with only two parameters and no output schema, the description covers the full workflow, the output format, and the intended use cases. Annotations handle the safety profile, so the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, with both parameters (url and max_links) already well-described in the schema. The description does not add any additional parameter-specific details, but it does reinforce that the tool works for 'any URL'. This meets the baseline for high schema coverage without requiring compensation.

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

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

The description opens with a specific action ('Generate a production-ready llms.txt file for any URL') followed by a clear explanation of the process and output. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than visibility auditing, and the use cases further clarify its unique role.

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

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

The description lists explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), which gives clear context for when to use it. It does not explicitly name alternative tools or exclusions, but the use cases create enough differentiation for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds value by specifying that the list is scoped to the caller, includes only active subscriptions by default, and returning the exact field set. This 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 concise, information-dense sentences. The first states the purpose and return fields; the second gives usage guidance. No redundant words or repetition of schema/annotation details.

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

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

Despite lacking an output schema, the description lists all return fields and clearly explains the tool's scope. With a single optional parameter and clear sibling context (subscribe/unsubscribe), this is complete enough for a read-only list operation. Minor omissions like pagination or sorting are not critical here.

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 single parameter include_inactive is fully described in the schema (100% coverage), including its default behavior ('default false'). The description adds no additional parameter semantics, so the baseline of 3 is appropriate when the schema already handles the parameter.

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

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

The description uses the specific verb 'List' with a clear resource ('active subscriptions') and names the exact return fields (id, type, params, etc.). This distinguishes it from sibling tools like subscribe and unsubscribe, making its function immediately obvious.

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

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

The description explicitly states when to use the tool: 'before adding more' and 'to find an id to cancel.' This provides clear usage context and implicitly differentiates from subscribe/unsubscribe, though it does not explicitly name those 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 are all false and offer no safety hints, so the description carries the burden. It discloses that the team reads digests daily, feedback affects roadmap, and the tool is rate-limited to 5 per identifier per day and free. It doesn't explicitly state the message is transmitted to Pipeworx servers, but 'Tell the Pipeworx team' implies that.

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

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

The description is longer than average but each sentence earns its place: purpose, usage triggers, exclusions, content guidance, outcome, and rate limit. It is front-loaded with the core purpose and well organized, though slightly dense.

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 feedback tool with 3 parameters, a nested object, and no output schema, the description is remarkably complete. It covers what the tool does, when to use it, when not to, how to structure input, constraints, and expected impact. No critical usage information is missing.

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

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

Schema already covers 100% of parameters with descriptions, so baseline is 3. The description adds practical meaning by explaining how to frame the message and context: refer to Pipeworx tools/packs, avoid pasting user prompts, keep to 1-2 sentences. It also connects the type enum values to real-world bug/feature/praise scenarios.

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

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

The description clearly states the tool's purpose: tell the Pipeworx team about something broken, missing, or needed. It immediately distinguishes this feedback tool from sibling tools by focusing on reporting issues to the team rather than querying or acting on data.

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 categories (bug, feature/data_gap, praise) and a clear when-not-to-use condition: only for Pipeworx-served tools, not other MCP servers, with an alternative of filing with that server instead. It also gives content guidelines (describe in terms of Pipeworx tools/packs, don't paste end-user prompts) and a rate limit.

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?

Despite annotations already declaring readOnlyHint and idempotentHint, the description adds valuable context: it mentions the data is cached for 5min-1h depending on the window, contains no PII, and has a specific data shape '(pack, tool, count)'. It also notes it is derived from CF analytics-engine, giving the agent confidence about the data source without contradicting any annotations.

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

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

The description is appropriately sized and well-structured: a concise opening sentence, a clear list of use cases, and a final sentence with technical caveats. No word is wasted, and each clause adds information that is not already in the schema or annotations.

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

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

With no output schema, the description adequately explains return values ('Returns the top tools, top packs, and total call volume') and data shape ('just (pack, tool, count)'). The tool is simple (one optional parameter), annotations cover safety, and the description covers caching and privacy, so it is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% for the single optional 'window' parameter, and the schema description already explains the enum values and their tradeoffs. The tool description only restates 'over a recent window (24h, 7d, or 30d)' and adds cache timing tied to the window, which is minor. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb ('Returns') and clearly identifies the resource ('top tools, top packs, and total call volume') and scope ('over a recent window'). It distinguishes itself from siblings by emphasizing this is a self-aggregating signal of what other agents are calling on Pipeworx, distinct from discovery or alert 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 'Useful for' section explicitly lists three concrete use cases: discovering hot data sources for current events, confirming canonical tools, and aligning with typical agent needs. However, it does not explicitly mention when not to use it or name alternative tools (e.g., discover_tools), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond by explaining the fill check (theoretical_edge_pp_at_book vs realizable_edge_pp), the semantic anchor threshold (≥0.30 Jaccard similarity), and partition filtering (placeholder fraction >20% returns null). This discloses edge-case behavior and limits not visible in structured fields.

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

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

The description is long but densely informative, with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a defined response structure. It is not wasteful; however, it could be tightened slightly (e.g., some repetition of 'event' explanation). Very near-optimal for a complex tool.

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

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

With no output schema, the description fully covers return values: opportunities[], partition_check fields, and fill-check outputs. It also addresses failure modes (skipped_low_similarity, null arb signal) and operational cautions (realizable_edge_pp ≤ 0). This is complete for a tool of this complexity.

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

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

Schema description coverage is 100%, but the description adds rich meaning beyond the schema: it explains each mode's internal logic, gives multiple examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and clarifies that full URLs are accepted. This goes well beyond the baseline 3 for full schema 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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates from siblings by detailing its unique mechanism and explicitly references polymarket_fill_risk for custom sizing, distinguishing its scope.

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

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

It provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative tool ('For custom sizing use polymarket_fill_risk') and gives a concrete caution ('do not trade it' when realizable edge ≤ 0).

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 mark it read-only and non-destructive, and the description goes far beyond: it details the response segments (by_segment, fed_candidates, _diagnostics), the 24h-move warning, Kelly caps, filter thresholds, placeholder-slug rules, and caching behavior ('Cached 1h at the KV level'). No contradiction with annotations; this exceeds the transparency bar.

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

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

The description is structured with ALL-CAPS headers, numbered model families, and clear segmentation, making the dense content navigable. It is verbose (roughly 300 words) but nearly every sentence adds unique detail, and the front-loaded purpose sentence grounds the reader. Minor redundancy (e.g., knob explanations repeated in the description and schema) keeps it from a 5.

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

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

Despite no output schema and 9 parameters, the description fully specifies the response top-level structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.), filtering rationale, and even why Fed bets are excluded. This leaves no major context gaps for an agent to invoke the tool.

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

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

The input schema already covers 100% of parameters, so the baseline is 3. The description adds extra semantic context by grouping knobs (e.g., 'TRADEABLE-EDGE KNOBS') and explaining subtle behaviors like partition_overround always returning kelly_fraction_half=0 at the parent level, which clarifies why min_kelly doesn't apply to partitions. This gives it a clear edge over the bare schema.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' — a specific verb, resource, and purpose. It is explicitly positioned as a discovery tool ('what should I bet on today') and outlines distinct model families (model_driven, structural_arbitrage, concentrated_longshot), which clearly differentiates it from sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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

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

Gives a clear use case ('agents discover opportunities without paging hundreds of markets') and explains how knobs like min_liquidity/max_spread_pp filter tradeable edges, and how min_partition_leg_kelly works for partitions. However, it does not explicitly say when to choose this over sibling tools (e.g., polymarket_arbitrage) or state negative usage scenarios, so it stops short of full when/when-not guidance.

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

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

Beyond the read-only/idempotent annotations, the description discloses critical behavioral details: the response structure (tracked, expired, snapshot_dates), the 60-day snapshot TTL limit, data gaps on cache-miss days, and that decay is based on daily closes of edge_pp_net (not intraday). This is rich, non-redundant 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 dense but well-organized with clear Args, RESPONSE, and LIMITS sections. Every sentence contributes new information, and the structure aids readability despite the length, avoiding any 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?

With no output schema, the description fully explains the return values (tracked, expired, snapshot_dates) and their semantics, including edge cases like gaps and TTL. This is exceptionally complete for a tool of this complexity, leaving little ambiguity.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds value by explaining 'days' as lookback with defaults and max, and 'window' as a snapshot family (24hr | 1wk | 1mo), giving conceptual meaning beyond the schema's type/description.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry' that answers 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by emphasizing historical tracking over snapshots, making its unique value explicit.

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

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

The description provides a strong use-case framing ('Answers how long...'), and the example about a fresh vs. 3-week-old edge implies when to use this tool. However, it does not explicitly name alternatives or state when not to use it, relying on the sibling list and 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 indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context beyond annotations: it walks the order-book ladder, returns slippage and fill prices, provides a verdict (clean/degraded/cannot_fill), and warns that partial basket fills convert an arb into an unhedged directional position. This is exactly the kind of behavioral disclosure needed, and it does not contradict 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 a single dense paragraph, but every sentence carries useful information including modes, parameters, outputs, and risk warnings. It is front-loaded with the main purpose. However, it could be better structured with bullet points or section breaks to improve scannability given the length and complexity.

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

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

For a tool with no output schema, the description provides extensive details on return values: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk. It also covers both modes and the practical context of when to use the tool, making it fully complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning beyond schema. It explains size_usd as "max spend on buys, target proceeds on sells" in single-market mode and as "settlement notional S (shares per leg; each share pays $1)" in basket mode. It also clarifies how side defaults work in basket mode based on partition sum. This greatly enriches parameter understanding.

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

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

The description opens with a specific, precise statement: "Realizable-vs-theoretical edge check against live CLOB order-book depth." This clearly names the verb (check), resource (edge against live depth), and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation.

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?

Usage guidance is explicit and actionable: "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500." It also clarifies when to use single-market vs basket modes, and explains why (partial fills create unhedged directional risk). This provides clear when-to-use and differentiates from alternatives.

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

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

The annotations already declare read-only/idempotent behavior, and the description substantially adds safety semantics: compatibility_warning conditions, temporal_alignment meaning, skipped_cross_type/subtype counters, and the warning that pre-mapped ≠ tradeable. This goes far beyond the structured fields, fully disclosing interpretation caveats and edge cases.

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 structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence provides operational information or caveats. It is front-loaded with the core definition and ends with a critical real-world caveat, making the length 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?

For a complex cross-venue tool with no output schema, the description covers the response format (leg prices, top_spreads_pp, compatibility_warning), temporal alignment semantics, why spreads may be invalid, and the rarity of actual tradeable spreads. This gives an agent enough context to invoke it correctly and interpret results, especially with annotations covering safety.

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 for all three params, so the baseline is 3; the description adds meaningful semantics by explaining the two modes, what each field overrides, and the behavior of the topic shortcuts (auto-fetch matching event on each venue). This lifts it above baseline but the schema already lists the enum values and override descriptions, so it's not a 5.

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

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

The description clearly defines the tool as calculating the cross-venue spread between Kalshi and Polymarket for the same resolving question, with explicit two-mode operation and response content. The specific mention of event pairing and compatibility warnings distinguishes it from generic market data tools, even though no sibling tool is named.

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

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

It provides clear context on when to use the tool—when needing the same-outcome price difference across Kalshi and Polymarket—and explains the two invocation modes (topic shortcuts vs explicit tickers). It warns that most pre-mapped topics are not actually tradeable, which guides appropriate expectations, but it doesn't explicitly name alternative tools for single-venue or arbitrage analysis, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: it explains scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving vs listing. No contradiction with annotations.

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

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

Three sentences, each earning its place: function, use cases, and scope/relationship. No filler, front-loaded with the core action.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what it does, when to use it, scoping rules, and its relationship to siblings. It hints at return values ('Retrieve a value' / 'list all saved keys'), which is sufficient given 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%, so the baseline is 3. The description reinforces the parameter semantics by explaining that 'key' refers to a value previously saved via 'remember' and reiterates that omitting it lists all keys. This adds meaning beyond the schema's terse 'omit to list all keys'.

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

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

The description uses a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and explicitly distinguishes the two modes: retrieving a value or listing all keys. It also differentiates from siblings by naming 'remember' and 'forget' as the save/delete counterparts.

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

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

Provides clear context for when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and explicitly names alternatives for related operations: 'Pair with remember to save, forget to delete.' This gives the agent actionable guidance on tool 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?

The description discloses crucial behavioral nuance beyond the annotations: mark_read:true modifies the read state, a side effect not captured by readOnlyHint=true. It also explains the persistent nature of the feed and the alternate URL for external access. This transparency is especially valuable given the annotations might otherwise mislead an agent into thinking the tool is completely read-only.

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, front-loaded with the core purpose ('Pull fired events from your subscription feed'), and each sentence adds distinct value: return format, filtering, mark_read behavior, and polling/alternative access. No fluff or repetition; it is appropriately sized for the tool's simplicity.

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?

In the absence of an output schema, the description helps by mentioning that returned events carry 'source, citation_uri (pipeworx:// when available), and the raw event payload.' It also covers filtering, mark_read semantics, polling suitability, and an external mirror URL. It does not discuss edge cases like pagination or errors, but for a read-oriented tool with good annotations, this is largely sufficient.

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

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

Although the schema already describes all 5 parameters (100% coverage), the description adds practical meaning by giving a concrete type example ('sec_8k'), noting the ISO timestamp format for 'since', and explaining the consequence of mark_read ('so the next call only shows newer ones'). This goes beyond the schema's one-line descriptions, enhancing the agent's understanding of how to use the parameters effectively.

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

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

The description uses the specific verb 'Pull' and 'Returns' with a clear resource: 'fired events from your subscription feed.' It distinguishes itself from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which sounds like changes, not alerts). The mention of 'persisted feed' and the event payload further pins down its purpose.

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

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

The description gives clear usage context: 'Filter by type (e.g. "sec_8k") and/or since' and 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' It also notes 'Polls work fine' and provides an alternative for scripts/dashboards via a URL, which helps the agent decide when to use the tool. However, it does not explicitly contrast with sibling tools, only implying that this is for reading alerts as opposed to managing subscriptions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), it discloses the multi-source fan-out, fallback chain, USPTO soft-fail due to PatentsView API sunset, and the exact return structure (changes[] grouped by source + total_changes + citation URIs). No contradictions with 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 dense but efficiently organized: query intents, fan-out behavior, parameter format, return format, and alternative tool. It could be slightly trimmed (six query examples are redundant), but every sentence serves a purpose and the structure is easy to scan.

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

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

For a multi-source, fallback-capable tool with no output schema, the description covers purpose, parameter formats, source behavior, and return values. It also addresses the one relevant sibling tool. Complete for an agent to select and invoke correctly.

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

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

Schema covers 100% of parameters with detailed descriptions and examples. The description reiterates `since` relative shorthand and typical monitoring values, but adds no parameter-specific semantics beyond the schema. It does contextualize why the parameters matter (parallel call, source grouping) but offers no new meaning.

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 multiple natural-language query examples and then states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly names the fan-out sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from sibling entity_profile by naming it directly.

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

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

Explicitly advises 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also gives clear use-case examples and documents fallback behavior (GDELT→GNews when rate-limited or 5xx), setting expectations for when and how to rely on this tool.

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

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

The description adds valuable behavioral context beyond annotations: key-value pair scoping, persistent memory for authenticated users vs. 24-hour retention for anonymous sessions. This complements the annotations (readOnlyHint false, idempotentHint true) without contradiction, providing a fuller picture of the tool's behavior.

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

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

Description is appropriately concise and front-loaded: the first sentence states the primary action, followed by usage guidance, storage characteristics, and companion tool references. Every sentence adds value with no fluff 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?

For a simple 2-parameter write tool with no output schema, the description covers purpose, when to use, persistence semantics, scoping, and related tools. There is no significant missing context; the annotations handle non-destructiveness and idempotency, completing the picture.

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

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

Input schema covers 100% of parameters with descriptions and examples. The description adds minimal parameter meaning beyond restating key-value storage, though it does suggest the kinds of value content (findings, addresses, preferences, notes). Since schema coverage is high, a 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?

Clearly states the tool's purpose with a specific verb ('Save data') and identifies what it saves (data for reuse later). Provides concrete examples (resolved ticker, target address, user preference, research subject) and distinguishes it from sibling tools by explicitly naming recall and forget as companions.

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?

Gives clear context for when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also instructs to pair with recall for retrieval and forget for deletion, effectively guiding usage relative to related tools. However, it doesn't explicitly state when not to use it, leaving alternative storage mechanisms unaddressed.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it reveals internal cascading through multiple lookup endpoints, auto-disambiguation behavior, and specific return details such as citation URIs. This enriches the agent's understanding of what happens during invocation.

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 two sentences but each sentence adds value. It is well-organized with 'SUPPORTED TYPES' and example queries, making it scannable. While dense, it avoids redundancy and is appropriately sized for a tool with this behavior and return complexity.

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

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

The description covers the tool's purpose, supported entity types, input formats, output details for both types, and rationale for use. Given there is no output schema, the description effectively explains return values. Minor gaps like error handling on unknown names are not covered, but for a resolver tool with rich annotations, this is nearly 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% and already describes both parameters with examples. The description restates this and adds 'auto-disambiguated,' but that is more behavioral context than parameter semantics. It does not significantly deepen the meaning of the parameters beyond what the schema provides, 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 uses the specific verb 'resolve' and clearly identifies the resource: user-spoken names mapped to canonical identifiers. It provides concrete example queries and distinguishes itself from typical lookup tools by emphasizing that it returns official identifiers required by other tools. This is unambiguous and differentiated 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 FIRST whenever you have a name but need an ID,' giving clear priority and context. It also explains that using resolve_entity replaces 2-3 manual lookups, which indirectly positions it against alternatives. However, it does not explicitly name alternative tools or state when *not* to use it.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context by explaining the internal process (probes each entity with ai_visibility_check, ranks by score) and output structure (ranked list with score, confidence, signal density). It does not discuss rate limits or error handling, but the added process detail 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?

The description is three sentences, front-loaded with the primary action, followed by scope and use case. Every sentence contributes information without redundancy. It is concise and well-structured.

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

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

The description explains the output format (ranked list with score, confidence, signal density), the use case, and how the tool relates to ai_visibility_check. However, it lacks details on error behavior, rate limits, or how the ranking is computed beyond 'by score'. Given the tool's moderate complexity and absence of an output schema, this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all parameters including the 'first entry treated as subject' behavior. The description does not add much beyond the schema; it restates the models options that are already in the parameter descriptions. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This specific verb+resource+scope distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic 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 explicitly mentions the tool is useful for competitive AI-marketing audits and gives an example query. It implicitly differentiates from ai_visibility_check by focusing on multiple entities, but does not explicitly state when not to use it or name alternative tools for single-entity checks.

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

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

Annotations already declare readOnly, idempotent, non-destructive, but the description goes beyond by disclosing graceful degradation on partial failures, the 5-30s first-measurement timeout for bundlephobia, and the sources_failed field. It also notes NPM-only v1 scope. 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 five dense, information-rich sentences, each earning its place: purpose, usage, output fields, ecosystem scope, and failure behavior. It is front-loaded with the main check and avoids redundant repetition of the title or schema.

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

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

For a composite tool with multiple data sources, the description fully accounts for complexity: it lists output fields, mentions per-advisory detail and links, specifies ecosystem limits, and explains timeout/partial-failure behavior. With no output schema, the description itself supplies the necessary return-value context.

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

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

Schema coverage is 100%, so baseline is 3. Both parameters have clear descriptions in the schema (package name with scoped support, version defaulting to latest). The description adds no new parametric meaning beyond what the schema already provides, though it does contextualize the parameters within the composite check.

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

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

The description opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call' and explicitly names the two fan-out sources (deps.dev and bundlephobia). It clearly distinguishes this tool from siblings (none of which are npm package analysis) and states the ecosystem limitation.

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

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

Explicit usage triggers are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a when-not: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing users to alternative handling for other ecosystems.

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

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

Goes beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by disclosing the embedding model (BGE-base-en), windowing strategy (500-char overlapping), output features (character offsets, similarity scores), and truncation behavior with flagging. 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?

Every sentence earns its place: purpose, use case, workflow pairing, and technical details are packed efficiently. No redundancy or filler; the description is front-loaded with the core function.

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 no output schema, the description compensates by explaining what the agent gets back (top-N passages with offsets and scores), the operational constraints (200K cap, truncation flag), and the integration with another tool. This is fully complete for selecting and invoking 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 already covers all parameters with descriptions, so baseline is 3. The description adds meaningful examples for the query parameter and clarifies the 'text' parameter context (already-fetched record, size cap), enriching understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record (specific verb+resource), and explicitly contrasts with sibling tools by emphasizing it works on text already pulled. It distinguishes itself from broader search tools like box_search or ask_pipeworx by its 'INSIDE a fetched record' scoping and output of passages with offsets.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for a workflow. It also sets expectations about input size cap, making the usage context clear.

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

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

Annotations only indicate read/write/destructive/idempotent hints. The description adds substantial behavioral context: OAuth requirement (anonymous/BYO can't persist), delivery channel specifics (feed always on, email/SMS/webhook), SMS verification and cap, webhook signing secret returned only once, and auto-disable after 10 consecutive failures. This goes well beyond the structured annotations.

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

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

The description is a single dense paragraph that front-loads the main purpose and then systematically covers types, examples, and delivery channels. While long, every clause adds useful information; no redundant filler. It could be broken into clearer sections, but the structure is logical 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 tool with nested objects and no output schema, the description is remarkably complete. It covers purpose, return value, prerequisites, supported types with examples, all delivery channels, and critical constraints (verification, caps, webhook signature). The agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the always-on feed and how to pull it (via recent_alerts or GET registry.pipeworx.io/alerts.json), plus reinforcing SMS constraints and webhook verification rules. This provides operational detail not explicitly in the schema.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes it from siblings like list_subscriptions, unsubscribe, and recent_alerts, which are about managing or reading subscriptions rather than creating one.

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

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

It provides clear context for when to use the tool (e.g., monitoring live-data event streams) and detailed conditions (requires OAuth account, types available), but doesn't explicitly name alternatives or when-not-to-use cases. This falls short of the 'explicit when/when-not/alternatives' bar but exceeds simple implied usage.

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

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true, destructive=false. The description adds behavioral context beyond annotations: it returns category-bucketed questions drawn from a live catalog, and explains the output shape. No contradictions. Slight deduction because it doesn't discuss rate limits or side effects, but annotations cover safety.

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

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

The description is a single dense paragraph, but every sentence earns its place. It front-loads natural language queries and then explains the output and usage. Slightly long, but appropriate for the tool's complexity and the need to convey onboarding 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 tool's complexity, presence of annotations, and lack of an output schema, the description fully covers return value structure (category-bucketed examples with tool+argument shape), argument behavior (with/without topic), and when to use. 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 has 100% coverage for the single optional `topic` parameter. The description adds meaning by enumerating example topic values ('finance', 'pharma', 'betting') and explicitly stating that omitting `topic` yields a cross-category spread, which goes beyond the schema's simple description.

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

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

The description uses a specific verb ('suggest questions') and clearly states the resource (Pipeworx's capabilities). It distinguishes itself from siblings by positioning as the 'onboarding entry point' and listing what it returns (category-bucketed example questions with exact tool + argument shape). No ambiguity.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also gives guidance on when to pass `topic` vs omit, effectively covering context and alternatives.

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

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

The description discloses that the row is deactivated rather than deleted, which directly explains the non-destructive behavior beyond the annotations. It also adds the ownership enforcement detail and notes that historical events remain available via 'recent_alerts'. This provides valuable context that the annotations alone do not convey, and there is 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 extremely concise, using only two sentences. The first sentence delivers the core purpose immediately, and the second adds relevant constraints and side effects without any fluff. Every word 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 and no output schema, the description fully covers the necessary context: the action, the ownership constraint, the non-destructive behavior, and the impact on historical events. It is complete for an agent to invoke the tool correctly.

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

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

The schema coverage is 100%, and the parameter 'id' is already well-documented as the subscription id returned by 'subscribe'. The description simply repeats 'by id' without adding additional parameter-level context. Baseline 3 is appropriate because the schema handles the parameter meaning.

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

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

The description states the action explicitly: 'Cancel a subscription by id.' It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the operation and the ownership constraint. The scope is precise 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?

It provides clear context for when to use the tool (cancelling a subscription) and an important constraint (only your own subscriptions). It does not explicitly name alternative tools, but the purpose is self-evident and ownership enforcement is a practical guideline. A slight improvement would be to mention 'list_subscriptions' as the counterpart for viewing active subscriptions, but the guidance is adequate.

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 non-destructive. The description adds significant behavioral context beyond the schema: it explains the exact percent-delta math, the automatic fallback to a grounded pipeline, the specific verdict categories returned, citation format, and that it replaces multiple sequential calls. This is valuable and does not contradict annotations.

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

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

The description is moderately long but packed with essential details: examples, use case, pipeline routing, output verdicts, and efficiency benefit. It is front-loaded with natural-language triggers and remains logically structured. Every sentence contributes value, though slightly verbose compared to minimal examples.

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

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

This is a complex tool with two execution paths and no output schema, so the description carries the full burden of explaining return values and behavior. It covers the verdict types, actual value with citation, reasoning, and the routing logic. The parameter examples and tolerance guidance complete the picture, making it fully contextual for an agent.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds extra meaning: it provides realistic examples for 'claim', clarifies that tolerance_pct overrides claim wording, and recommends 1-2% for hallucination detection. This goes beyond the schema's basic type/description.

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

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

The description uses a specific verb 'validate' with a clear resource (factual claims) and states it performs natural-language claim verification. It distinguishes itself from siblings by detailing the verdict output and the two distinct pipelines (SEC EDGAR for financial claims, grounded pipeline for others), making it unmistakable what this tool does.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is a clear trigger. It also delineates the behavior for company-financial versus other claims, but does not explicitly name alternative tools for non-verification queries (e.g., ask_pipeworx), so it lacks an explicit when-not-to-use or alternative comparison.

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