trivia

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description adds beyond that by disclosing the default model ('Workers AI Llama-3.3-70b (free)') and the cost implication of using Anthropic ('BYO key — you pay Anthropic directly for those calls'). This provides useful context 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 two sentences, front-loaded with the core purpose, and every clause adds value. It avoids redundancy with the schema and annotations while covering key details like return format and use cases.

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

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

With no output schema, the description compensates by specifying the return shape: 'per-model {score, confidence, signals, raw_response} + a combined view.' Combined with the annotations and schema, the tool is fully specified for safe and correct use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the default model for the 'models' parameter and clarifying that `_apiKey` is only needed when 'anthropic' is specified. This gives the agent a better understanding of parameter interplay beyond the schema.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses specific verbs and resources, and the focus on per-model visibility scoring distinguishes it from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence'.

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

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

The description provides clear usage context by naming concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the optional `_apiKey` parameter. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a full 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 provide readOnly/openWorld/idempotent hints, and the description adds substantial behavior beyond them: the routing mechanism, automatic argument filling, and the stable pipeworx:// citation URI return format. This tells the agent what actually happens at invocation, which the annotations do not convey.

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

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

The description is long but densely packed and logically ordered: preference rule, behavior, trigger phrases, examples, step-up alternatives. Every section earns its place. Minor deduction for a slightly garbled transition ('single-turn, step up only when needed: for...') that reads like a truncated editing artifact, and for the duplicate mention of web search near the end.

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

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

For a router tool over 5,798 tools with no output schema, the description is remarkable complete: it covers when to choose this tool, what it returns (structured answer + citation URIs), when to escalate to grounded or deep_research, and how breaking-news is handled. An agent has everything needed to invoke and interpret the result.

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% (all six params documented as aliases for question), so baseline is 3. The description adds value above baseline by clarifying what kinds of questions are acceptable, supplying six example queries, and framing the parameter as a natural-language factual request. Minor deduction: it doesn't address length limits or formatting expectations.

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

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

The description states a clear verb-resource pair (routes a question to one of 5,798 tools across 1,517 verified sources) and enumerates specific domains (SEC filings, FDA data, economic stats, patents, weather, clinical trials, etc.). It explicitly contrasts itself with siblings (ask_pipeworx_grounded, deep_research, web search), making selection 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?

Gives an explicit 'PREFER OVER WEB SEARCH' directive, lists trigger phrases ('what is', 'look up', 'find', 'get the latest'), provides concrete examples, and names the exact step-up conditions for ask_pipeworx_grounded and deep_research. This is exemplary when-to-use guidance with clear 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds valuable non-obvious behavior: it is a fully working router with no fallback, is currently identical to the stable ask_pipeworx, and may change when a candidate is under test. No contradiction with annotations exists.

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

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

The description is information-dense and front-loaded with the primary purpose and beta status in the first sentence. It conveys current behavior, experimental nature, and usage guidance in four sentences. Minor redundancy around 'full working router' and 'falls back to nothing' exists, but it does not meaningfully detract.

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 100% schema coverage, rich annotations, and a single required input, the description provides enough context for invocation. It does not detail the response shape beyond 'same response shape,' but because this is explicitly a beta alias of a known sibling router, that reference is reasonably complete. The absence of an output schema is partially compensated by the explicit parity statement with ask_pipeworx.

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 every parameter (question plus five aliases) already documented in the input schema. The description only says 'same arguments' without adding new semantic meaning or clarifying parameter usage beyond the schema. This aligns with the baseline of 3 when the schema already handles parameter documentation.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router' and clearly identifies this as the experimental variant of the stable router. It distinguishes itself from ask_pipeworx and the grounded sibling by tying it to 'candidate routing improvements' and the 'experimental edge,' so an agent can tell which tool is being described.

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 it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router, which gives clear when-to-use guidance. It also says no candidate is active right now, so it currently matches ask_pipeworx exactly. It does not explicitly mention when not to use it or name the grounded alternative, but the routing-intent guidance is sufficient.

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

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

Beyond the annotations (read-only, idempotent), the description discloses the exact success and refusal return shapes, the specific refusal reasons, and the extra LLM call cost. It also clarifies that the tool uses only the tool result for the answer, which is not visible in the annotations and is essential for safe invocation. No contradiction with annotations.

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

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

The description is dense but every clause earns its place: mode, routing behavior, return contract, refusal reasons, usage guidance, and cost tradeoff. The core purpose is front-loaded and the details are all decision-relevant for an agent.

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?

There is no output schema, but the description fully compensates by listing the success fields, refusal fields, and possible refusal reasons. Combined with annotations and parameter schema, the agent has everything needed to decide when to call this tool and what to expect from it.

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

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

The input schema has 100% coverage of the single logical question parameter and its aliases. The description adds context that the question is routed across many sources and tools, but it does not add much semantic detail beyond what the schema already documents, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant, grounded answer mode for high-stakes reads, and explicitly contrasts it with ask_pipeworx. It names a distinct behavior (extraction only from tool results, with explicit refusals) that separates it from siblings and from casual lookup 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 states exactly when to use this tool: whenever the answer will be quoted, cited, or acted on and factual invention is unacceptable. It also gives the alternative by saying to prefer ask_pipeworx for casual lookups, citing the extra LLM call cost as the tradeoff.

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, non-destructive) by disclosing critical behaviors: low-confidence short-circuit with status:'low_confidence_match', suppression of analysis fields for phantom matches, closed-market handling, wide-spread tradeability warnings, resolution-rule risk parsing, parent-event extraction, and news fallback failure reporting. Every safety and failure mode is surfaced, which is exemplary transparency.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). Every sentence carries operational detail. It is not as tight as a two-sentence description, but the density is justified for a complex tool with no output schema. The structure helps scannability, though it could be trimmed slightly without losing critical info.

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

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

Given no output schema and a complex tool with multi-source fan-out, the description covers response shapes, resolver confidence fields, parent-event details, news fallback mechanics, safety short-circuits, and cancellation-rule parsing. It also warns about recurring rules-based losses. This is a complete operational manual for safe and correct use, leaving no important context uncovered.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaningful value by detailing the market parameter input formats (slug, URL, question text) and providing concrete fan-out examples based on the market classification. It also explains the behavior of include_raw with payload size implications in the schema, but the description reinforces this. The fanned-out source examples for different bet types are additional semantic context that aids parameter selection.

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

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

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 distinguishes this from siblings by focusing on single-bet research with fan-out to category-specific data packs, while siblings like polymarket_arbitrage and polymarket_edges target market comparisons and edge detection. The purpose is explicit and unique.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains blocking behaviors for failed resolutions and closed markets. However, it does not explicitly name alternatives or say when NOT to use this tool, only implying that it is the go-to for single-bet research. This is clear context but lacks explicit exclusions.

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

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

Beyond the readOnlyHint annotation, the description discloses specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), how off-calendar fiscal years are handled, and that results are sorted by primary metric. It also mentions return of citation URIs, adding valuable behavioral context.

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

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

The description is dense but well-structured, moving from user intent examples to core functionality to type-specific behavior and output. Every sentence adds value with no filler; it is front-loaded with the key purpose and usage directive.

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 covers return format (paired data + citation URIs), sorting behavior, entity-specific data, and even fiscal year edge cases. It provides sufficient context for an agent to select and invoke the tool correctly without needing additional information.

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

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

Although the schema already covers both parameters 100%, the description significantly enriches meaning: for 'type' it lists exact metrics pulled (10-K revenue, net income, cash, long-term debt; FAERS counts, FDA approval counts, active trial counts), and for 'values' it provides example formats (tickers/CIKs, drug names) and clarifies the off-calendar fiscal year handling.

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 example user queries and then defines 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' clearly stating the verb, resource, and scope. It distinguishes itself from single-entity tools like entity_profile by emphasizing the parallel comparison and specific entity types.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and that it 'Replaces 8–15 sequential lookups,' offering direct guidance on when this tool is the right choice. This is a clear directive against alternative approaches.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavior beyond those: account and paid-tier requirements, internal decomposition into facets routed in parallel, a concrete findings packet with verbatim evidence/confidence/source/fetched_at/citations, gaps[] and contradictions[] semantics, semantic excerpting, citation resolvability, and latency estimates.

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 it is front-loaded with the most decision-critical facts: account requirement and the alternative tool. Every sentence carries behavioral or routing information; it loses a point only because the dense single-paragraph structure is harder to scan quickly than a more segmented description would be.

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

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

With no output schema present, the description carries the full burden of explaining return behavior, and it does: findings packet, hop field, citation_uri, gaps[], contradictions[], and large-record excerpting. It also covers auth, latency, depth effects, and exclusions, so an agent has enough to decide, invoke, and interpret results.

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

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

Schema coverage is 100%, and the description still adds meaningful parameter semantics: quick='single hop', standard adds a 'gap-recovery hop + contradictions[] scan', thorough='6 facets, paid, iterative hop'. It also tells agents that broad/multi-part questions are the intended shape for the question parameter, directly supporting correct invocation.

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 names a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources'. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell what this tool uniquely does without opening the schema.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'). It also names the exact alternative for unsigned-in agents: ask_pipeworx works on every tier.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context by stating that results include full input schemas with curated examples and are 'ready to call directly, no second schema lookup needed.' This goes beyond the structured annotation info.

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

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

The description is moderately lengthy due to the domain list, but that list is useful for scoping. It starts with a clear purpose statement and follows with usage and return details. Every sentence carries useful information, though slightly verbose.

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?

There is no output schema, but the description thoroughly explains what is returned: top-N tools with names, descriptions, and full input schemas. It also clarifies the ideal usage scenario. For a meta-tool of this complexity, 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%, so the schema thoroughly documents all six parameters. The description mentions 'top-N' which relates to the limit parameter, but the schema already explains it. The description does not add substantial parameter semantics beyond what the schema provides; baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It enumerates specific domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes this as a discovery tool for browsing the toolset. This is a specific verb+resource 'Find tools' with clear scope.

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

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

The description provides explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This gives clear context, though it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, and the description goes far beyond these by disclosing fan-out sources, soft-fail behavior for USPTO, the expected-empty semantics for FDA products, sources_used/sources_failed, and the resolved:false behavior for private companies. This is exemplary behavioral disclosure.

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 query examples and the always-prefer directive. It is long, but the length is justified by the number of sources and edge cases; however, the single run-on paragraph structure could be improved with lists or separate breaks for readability.

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

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

There is no output schema, so the description fully carries the burden of explaining return values. It enumerates cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used, and sources_failed, including semantics for empty sections. The tool is complex, and the description covers all important calling and interpretation scenarios.

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 genuine semantic value by explaining that 'type' accepts company/ticker interchangeably, that value can be a ticker/CIK/name, and that names resolve via SEC EDGAR, including resolved_from/resolved_to behavior 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 states a specific verb-resource pair: it provides a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from chaining single-pack lookups and from generic research or entity-resolution tools, so an agent can select it confidently.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies accepted inputs (ticker, CIK, company name) and the expected behavior for unsupported private companies, giving clear when-to-use and edge-case guidance.

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

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

The description discloses the destructive nature of the operation ('Delete') and adds context about clearing sensitive data, which goes beyond the annotations (destructiveHint: true, idempotentHint: true). It does not describe edge cases like missing keys, but the annotations already cover the idempotent behavior, and the description is consistent with 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 two sentences long, with the primary action front-loaded ('Delete a previously stored memory by key'). It provides usage guidance and tool pairing without any redundant or filler content, 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?

Given the tool's simplicity (one parameter, no output schema) and the presence of annotations for destructive and idempotent behavior, the description adequately covers the what, when, and how. It could mention the result of deleting a non-existent key, but the idempotent annotation implies a no-op, so the current description is sufficient for a tool this straightforward.

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

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

The input schema has 100% coverage for the single parameter 'key', with the description 'Memory key to delete'. The tool description adds no additional parameter meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Delete' with the resource 'previously stored memory by key', clearly stating what the tool does. It distinguishes itself from sibling tools 'remember' and 'recall' by describing its delete action, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with 'remember and recall', providing clear context for how this tool fits among alternatives. Although it doesn't explicitly list when not to use it, the guidance is sufficient for practical decision-making.

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

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

The description discloses key behavioral traits beyond the annotations: it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is a 'single text blob ready to drop at site-root/llms.txt.' Annotations already declare read-only, idempotent, and non-destructive behaviors, and the description is consistent with 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 two concise sentences plus a short list. It front-loads the primary purpose and immediately gives the process and output, avoiding redundant 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?

The tool has only two parameters, and the description explains the entire workflow (fetch, extract, emit) and the return value (a markdown blob). While it doesn't cover edge cases like JavaScript-rendered pages, the description is sufficient for an agent to understand when and how to use 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 provides full descriptions for both parameters (url and max_links), including default and max values. The description adds contextual meaning by mentioning 'any URL' and the extraction process, but does not introduce new parameter details beyond the schema.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It explains the process (fetches, extracts, emits) and the output format, which uniquely distinguishes it from sibling tools that focus on visibility checks or research.

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

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

The description provides explicit usage scenarios: '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.' It does not mention when to avoid the tool or name alternative tools, so it's clear context without 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, idempotentHint, and non-destructive behavior, lowering the burden on the description. The description adds transparency by specifying the output granularity (total plus easy/medium/hard counts) and the dependency on a category ID from list_categories, which is useful 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 compact, with the core purpose in the first sentence and a clarifying follow-up sentence. The opening noun phrase 'Question inventory' is slightly awkward, but the text is efficient and front-loaded with the essential information.

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

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

With only one parameter, a fully descriptive schema, and an output schema present, the description provides sufficient context for tool selection and invocation. It integrates the dependency on list_categories and the pre-quiz use case, making it complete for the tool's simplicity.

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

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

Schema coverage is 100%, and the parameter description already explains 'category' as a numeric ID sourced from list_categories. The tool description repeats this guidance without adding new parameter-level detail, so it meets the baseline but does not exceed 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 clearly identifies the tool as providing a question count inventory for a single Open Trivia Database category, explicitly stating it returns total and difficulty-specific counts. It distinguishes itself from sibling tools like list_categories and get_questions by specifying the input is a numeric category ID from list_categories and that it answers pre-quiz count questions.

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

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

The description implies the intended use case—checking question counts 'before requesting a quiz round'—and directs users to list_categories for valid IDs. It does not explicitly contrast with alternatives like get_questions or suggest_questions, but the context and references provide sufficient guidance for appropriate use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and mutability. The description adds no extra behavioral details (e.g., return limits, error behavior) beyond what annotations provide, so it is consistent but not enriching.

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 one concise sentence that front-loads the core action and mentions optional filters without waste. 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?

The tool is a simple read-only retrieval with only optional parameters. The schema defines all parameters and output schema exists, so the description need not explain return values or parameter syntax; it provides enough context for selection.

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

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

The input schema has 100% coverage with each parameter described (type, amount, category, difficulty). The description merely summarizes 'filter by category, difficulty, and question type' without adding detail beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves trivia questions from the Open Trivia Database and allows optional filters by category, difficulty, and type. This specific verb+resource combination distinguishes it from sibling tools like list_categories or suggest_questions.

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 does not provide any comparison or exclusion relative to sibling tools. It implies usage when trivia questions are needed, but lacks explicit guidance such as 'use this instead of suggest_questions when you need questions from the Open Trivia Database'.

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 some context by noting 'all available' and 'their IDs,' which clarifies scope and content, but does not disclose behaviors like sorting, pagination, or response size beyond what annotations cover. This meets the lowered bar set by annotations.

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

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

The description is a single, front-loaded sentence with no redundant words. It captures the essence of the tool without any filler, 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 parameterless list tool with a clear output schema and comprehensive annotations, the description is fully adequate. It does not need to explain return values because the output schema exists, and the simplicity of the operation leaves no major 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?

The tool has zero parameters, so the schema coverage is complete and no additional parameter explanation is needed. The description's mention of 'all available' implies a full listing with no filtering, which is consistent with the empty schema. Baseline for zero-parameter tools is 4.

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

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

The description clearly states a specific action (List) on a specific resource (trivia categories) and includes the output content (their IDs). It distinguishes itself from sibling tools like get_category_stats and get_questions, which likely operate on categories versus questions.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or common use cases like 'use this before fetching questions.' Without this, an agent may not know when to invoke 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 indicate readOnly/idempotent/non-destructive, so the bar for additional transparency is lower. The description adds the return field list and clarifies the scope ('caller's active subscriptions'). It does not contradict annotations and provides useful behavioral context beyond the structured data.

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: purpose, return fields, and usage guidance. Every sentence earns its place with no redundancy or fluff. It 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?

Given the simple tool (one optional param, no output schema), the description is complete: it lists return fields, specifies the default scope, and explains when to use it. No critical information is missing 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?

The input schema has full coverage (100%) for the single 'include_inactive' parameter, with a clear description in the schema. The tool description does not add any further parameter meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb ('list') and resource ('subscriptions'). It also lists the return fields, making its function unambiguous. This distinguishes it from the sibling tools 'subscribe' and 'unsubscribe'.

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

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

The description gives explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' It does not explicitly mention when not to use it, but the context is clear enough for a read-only list tool. This earns a 4 rather than a 5 because it lacks explicit alternatives/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 are all false/neutral, so the description bears the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the optional account-claim flow ('Filing without an account returns a claim_token'), follow-up semantics, and operational details like 'doesn't count against your tool-call quota.' This goes far 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 long but front-loaded: the main purpose and use cases come first, followed by exclusions and mechanics. Every sentence adds value. Slightly verbose with multiple caveats, but structurally sound and appropriately sized for a feedback tool that needs clear guidelines.

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 4 params, no output schema, and nested object, the description covers the full workflow: when to use, what to include, token handling, exclusions, and rate limits. There is no ambiguity left for the agent about how to invoke or follow up. Complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds workflow context: explains what claim_token does ('pass it back later... to read whether it was fixed'), and instructs on message construction ('Describe the issue in terms of Pipeworx tools/packs'). This is meaningful added semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature/data_gap, praise), making it unambiguous and distinguishing it from all sibling tools, none of which are feedback-related.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: tools from other MCP servers, and directs the user to file with that server instead. This is ideal usage guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context beyond this: it discloses the data source ('derived from CF analytics-engine'), the privacy property ('no PII'), and caching behavior ('Cached 5min-1h depending on window'). It effectively communicates the read-only, self-aggregating nature of the tool.

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

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

The description is a single, well-organized paragraph. It front-loads the core purpose, then provides a bullet-like list of use cases, and ends with additional data source and caching details. Every sentence earns its place with 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?

With only one optional parameter, no output schema, and strong annotations, the description still fully covers what the agent needs to know: what it returns (top tools, packs, call volume), when to use it, the data source, privacy, and cache timing. It is complete for a simple, read-only aggregation tool.

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

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

Schema coverage is 100% and the schema already provides a description for the window parameter. The description adds extra semantics by explaining that 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps the agent choose an appropriate value. This goes beyond simple schema repetition.

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 what the tool does: "What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window." It uses a specific verb ('Returns') and names distinct resources (tools, packs, call volume), making it easy to distinguish from siblings like discover_tools.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool choice, aligning with agent needs), providing clear context for when to use it. However, it does not name an alternative sibling or state when NOT to use it, so it falls short of the most explicit 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 this as read-only and idempotent, and the description adds substantial behavioral context beyond that: the semantic anchor (Jaccard similarity ≥0.30), the partition filter behavior (>20% placeholder fraction returns null arb signal), and the fill check semantics (realizable_edge_pp ≤ 0 means do not trade). 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 long but well-structured with uppercase section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose. Each section adds necessary operational detail, and no sentence is redundant, justifying the length.

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

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

Given no output schema, the description compensates by explicitly detailing response fields (opportunities[], partition_check) and edge-case behavior (null arb signal, fill check, realizable_edge_pp ≤ 0). It also covers when not to trade, making it complete for a complex tool.

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

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

While the schema provides descriptions for both parameters, the tool description enriches them with concrete examples, mode-specific behavior, and internal logic (e.g., 'walks child markets, checks date-axis / threshold-axis ordering', 'searches related events across the platform, flattens markets, runs the comparator on the union'). This goes well beyond the schema's baseline.

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

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

The description opens with a precise statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It names the specific resource and mechanism, and clearly differentiates three invocation modes (trending_scan, event, topic) making its purpose distinct 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 states when to call with no args (trending_scan), when to use event (recommended for a specific market), and when to use topic (cross-event scanning). It also points to a sibling tool for custom sizing ('For custom sizing use polymarket_fill_risk'), providing clear when-to-use and alternative guidance.

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

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

With annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, the description goes far beyond by explaining internal model families, response segmentation, filter behavior ('min_liquidity / max_spread_pp drop opportunities where edge isn't realizable'), the 24h-move warning, and even caching behavior ('Cached 1h at the KV level'). This provides deep, actionable context without contradicting annotations.

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

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

The description is a single, very dense paragraph with heavy use of all-caps labels, parentheses, and enumerations. It contains a lot of valuable information, but it lacks paragraph breaks or bullet points, making it hard to scan. While every sentence earns its place, the structure is not concise for an AI agent to quickly 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?

Given the tool's complexity (three model families, nine parameters, response segments, diagnostics, caching), the description is exceptionally complete. It describes the output shape top-level ('by_segment{...}, fed_candidates/fed_note, _diagnostics'), explains why segments might be empty (funnel counters, filter_skips), and documents caching. Even without an output schema, the description adequately covers behavior and return structure.

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 baseline is 3. The description adds meaningful context by grouping knobs into 'TRADEABLE-EDGE KNOBS' and explaining how parameters interact with segments (e.g., 'min_partition_leg_kelly' applies to per-leg Kelly inside top_legs, not parent level). This goes beyond the schema's individual parameter descriptions to convey the tool's internal logic and parameter interdependencies.

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+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's purpose and differentiates it from sibling tools by focusing on edge discovery rather than market listings or comparisons. The target use case ('what should I bet on today') further clarifies intent.

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 ('Built for ... agents discover opportunities without paging hundreds of markets') and explains the 'TRADEABLE-EDGE KNOBS' with concrete settings (e.g., 'Set to 2 to require tight books'). It also notes exclusions (Fed bets excluded from ranking) and diagnostic guidance. However, it does not explicitly name alternative sibling tools or say when *not* to use this tool.

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

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

Annotations already declare readOnly/idempotent/destructive, but the description adds significant behavioral depth beyond those hints. It explains how snapshots are written (on cache-miss), why gaps occur, the 60-day TTL bound, and that decay numbers come from daily closes 'not intraday.' It also clarifies the signed meaning of edge_pp_net and the trend classification logic. This is rich, actionable context that annotations alone do not provide.

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

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

The description is longer than average but every sentence earns its place. It is structured into Purpose, Args, RESPONSE, and LIMITS sections, making it scannable despite the density. The front-loaded purpose sentence immediately conveys the essence, and the later sections provide necessary detail. It is appropriately sized for a telemetry tool with nuanced interpretation; a shorter description would lose critical context.

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

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

Without an output schema, the description fully compensates by detailing the response shape: tracked[] with fields, expired[] with lifespan_days, and snapshot_dates[]. It also covers limitations (TTL, snapshot enabling, daily closes) and edge cases (gaps meaning no scan). For a tool with such complexity, this is complete and self-contained.

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

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

The input schema covers 100% of parameters with descriptions including defaults and clamps. The description adds complementary semantics: it calls 'window' a 'snapshot family' and reinforces the lookback default and max. This adds conceptual meaning (snapshot family implies grouping across time) beyond the schema's raw value descriptions, so a score above baseline is warranted.

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 precise noun phrase: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It then states the exact question it answers ('how long has this edge existed and is it shrinking?'), which clearly distinguishes it from sibling tools like polymarket_edges that likely provide current edge values. The purpose is specific and immediately recognizable.

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

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

The description explains when to use the tool by framing the problem: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It also gives context about snapshot gaps and TTL limits. While it doesn't explicitly name alternative tools, the implied contrast with snapshot creation and the 'daily polymarket_edges' reference make it clear this is for historical persistence rather than current edges.

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

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

Annotations already state readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: it 'walks the ladder', returns specific fields (top_of_book, vwap_fill_price, slippage_pp), handles partial fills, and flags forced directional risk. The risk of unhedged positions is disclosed. No contradiction with annotations.

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

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

The description is dense and long, but every sentence carries operational value. It is front-loaded with the core purpose, then systematically covers modes, parameters, outputs, and usage guidance. Minor deduction for being a wall of text; structured headings or bullet lists would improve scannability, but the content is appropriately detailed for such 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 must explain return values, and it does: single-market returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict; basket returns theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also contextualizes usage against sibling tools and warns about partial-fill risk, making it complete for an AI agent.

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

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

Schema coverage is 100%, but the description elevates parameter understanding by explaining mode-dependent semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market vs 'settlement notional S (shares per leg)' in basket; side defaults and auto-detection are clarified; and clamps are mentioned. This adds meaning well 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 opens with a crisp verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the tool's function (checking fill risk) from sibling tools like polymarket_arbitrage or polymarket_edges, and further delineates single-market vs basket modes.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also names the alternative tools and explains the risk scenario (partial basket fills converting to directional positions), making when-to-use and when-not-to-use 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 mark this as read-only/idempotent, but the description goes far beyond them: it discloses that spreads are gross, that Kalshi fees are not modeled, that compatibility_codes can be non-empty even when pairs are returned, and that matching is keyword/word-overlap based rather than a shared resolution source. This is rich, honest behavioral disclosure.

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 and dense, but it is sectioned (modes, response, safety fields, codes, fees, skipped counters) and nearly every sentence conveys necessary caveats or semantics. It could be trimmed, but the structure makes the length navigable.

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 values, and it does: leg-by-leg prices, top_spreads_pp, compatibility fields, per-entry flags, skipped_unclassified, temporal_alignment, fees_note, and skipped counters. For a tool with this many caveats, 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?

Even though schema coverage is 100%, the description adds substantial meaning beyond the individual parameter descriptions: it explains the three-parameter interaction, that explicit ticker/slug override the topic mapping, and that both modes run the identical token-overlap matcher. This is far more useful than the bare schema descriptions.

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

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

The description opens with a specific verb+resource: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also distinguishes itself from sibling tools like polymarket_arbitrage by emphasizing cross-venue comparison and price differences driven by differing participant pools.

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 operating modes (`topic` shortcuts vs explicit `kalshi_event_ticker` + `polymarket_event_slug`), explains when each is appropriate, and warns that pre-mapped topics are rarely tradeable. It does not explicitly name sibling alternatives or state when to prefer polymarket_arbitrage/edges, so it is not a full 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, idempotentHint, and destructiveHint. The description adds meaningful behavioral context, particularly scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key to list all saved keys. This supplements 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 two sentences, front-loaded with the core action, and every phrase adds value. It avoids repetition and irrelevant detail, making it highly concise and well-structured.

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

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

For a simple tool with one optional parameter, the description covers the retrieval behavior, list-all behavior, scoping, and relationship to sibling tools. There is no output schema, but the description sufficiently implies what is returned. It is complete for the tool's complexity.

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

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

The schema already provides 100% coverage for the only parameter (key), so the description adds little beyond what is structured. It offers illustrative examples of memory keys but does not introduce new semantic details, 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: retrieving a saved value or listing all saved keys when the key argument is omitted. It distinguishes itself from sibling tools by explicitly referencing 'remember' and 'forget' as paired operations, making its purpose unambiguous.

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

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

The description provides clear context on when to use the tool—'to look up context the agent stored earlier'—and gives concrete examples like target ticker and prior research notes. It also implies alternatives by pairing with remember/forget, but does not explicitly state when not to use it, so it falls short of a 5.

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

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

The description explicitly states that setting mark_read:true flags returned events as read, which is a state mutation. This contradicts the annotation readOnlyHint:true, which implies the tool does not modify state. Even though mark_read is optional, the tool's behavior under that parameter conflicts with the top-level annotation, making this a flagrant contradiction.

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

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

The description is concise and front-loaded with the core purpose. It packs in the return contents, filtering options, mark_read behavior, polling guidance, and an alternative URL—all in three sentences with no unnecessary 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?

Despite lacking an output schema, the description explains what each alert carries (source, citation_uri, raw payload), how to filter, the side effect of mark_read, and points to a polling-friendly alternative endpoint. This is a complete picture for a tool with 5 optional parameters.

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

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

The schema already covers all 5 parameters at 100%, so the baseline is 3. The description adds meaningful clarifications: gives an example value for type ('sec_8k'), notes since expects an ISO timestamp, and explains the behavioral effect of mark_read (so the next call only shows newer ones). This goes beyond the schema's basic 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 'pulls fired events from your subscription feed' and returns 'the most recent alerts' with source, citation_uri, and raw payload. This distinguishes it from sibling tools like list_subscriptions (which lists subscriptions) and recent_changes (likely a different resource).

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 usage context: 'Polls work fine' and notes the same feed is available via a public URL for scripts/dashboards, implying this tool is for interactive polling. It also explains how to use mark_read to see only newer events. However, it does not explicitly contrast with specific sibling tools or provide when-not-to-use scenarios.

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

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

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral context: it discloses the multi-source fan-out, the GDELT→GNews fallback on rate-limit/5xx, the USPTO soft-failure due to PatentsView API sunset, and the return shape (changes[], total_changes, citation URIs). No annotation 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 a single dense paragraph that front-loads natural-language queries and then packs source behavior, fallback logic, date formats, and output contract efficiently. No sentences are wasted; it is long but every sentence carries signal.

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 (multiple sources, fallback logic, date parsing, no output schema), the description is remarkably complete. It states what is returned, how sources are grouped, how failures are handled, and when to choose a sibling tool. This is sufficient 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?

The input schema already covers all three parameters with descriptions (100% coverage). The description adds meaningful syntax examples for since ('2026-04-01', '7d', '30d', '3m', '1y') and value (ticker or zero-padded CIK), plus a recommendation to use '30d' or '1m' for typical monitoring. This goes beyond the schema.

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

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

The description clearly identifies the tool as a company change feed over a time window, with specific trigger phrases like 'What's new with X' and 'updates on Acme'. It names concrete data sources (SEC EDGAR, GDELT/GNews, USPTO) and differentiates from entity_profile, which is the static-profile sibling.

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 when-to-use examples and an explicit alternative: 'Use entity_profile instead when you want the static profile...'. It also explains the one-call parallel fan-out behavior and the fallback from GDELT to GNews, which helps the agent decide when this tool is appropriate.

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

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

The description discloses important behavioral details beyond the annotations: storage as key-value pairs scoped by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. This adds valuable context about memory lifetime and authentication requirements that annotations do not convey. No contradiction with annotations (readOnlyHint false aligns with 'Save data').

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

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

The description is concise and well-structured: first sentence states the core purpose, second explains when to use, third covers storage and persistence details. Every sentence adds value without redundancy, making it easy for an agent to quickly extract the essential information.

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

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

For a simple two-parameter tool with no output schema, the description covers all necessary aspects: purpose, usage triggers, memory scoping, retention policy, and complementary tools. It is complete enough for an agent to select and invoke the tool correctly without further clarification.

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 fully documents both parameters (key and value) with examples. The description adds only marginal context like 'key-value pair scoped by your identifier,' which is more about storage model than parameter semantics. This aligns with the baseline 3 for high 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 clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb (save) and resource (data/memory). It distinguishes itself from siblings by naming recall and forget as complementary tools, and provides concrete examples of what to store (resolved ticker, target address, user preference, research subject).

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 when to use the tool: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with recall and forget, giving clear context on how it fits within the tool ecosystem. No when-not clauses, but the usage triggers are specific enough to serve as strong guidance.

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

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

Annotations already declare readOnly, openWorld, and idempotent behaviors, but the description adds substantial behavioral context: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, source labels for identifiers, ambiguity handling via `figi_candidates`, and the fact that one call replaces several manual lookups. This goes well 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 long and dense, but it is front-loaded with usage examples and the critical 'Use FIRST' instruction, and nearly every sentence adds new information. The parenthetical-heavy style makes it somewhat sprawling, so it is not perfectly concise, but it remains well structured for a tool with this much behavioral nuance.

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 present, the description carries the full burden of explaining return behavior. It covers multiple entity types, identifier sources, ambiguity, unresolved resolution, fallback behavior, and even non-US/non-equity edge cases. An agent has enough context to invoke the tool correctly and interpret its results.

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

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

While schema coverage is 100%, the description adds crucial semantics: company input accepts ticker/CIK/ISIN/name, drug input accepts brand or generic names, and it warns against passing the full noun phrase (e.g., 'revenue bonds'). This guidance prevents real misuse that the schema alone would not.

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

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

The description states a specific verb and resource: resolving a user-spoken name to canonical/official identifiers (CIK, ticker, LEI, FIGI, RxCUI). It includes concrete example phrasings and supported types (company, drug), making the tool's role unmistakable and clearly distinct from sibling tools like entity_profile or compare_entities.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' giving a clear trigger condition. It also explains accepted input forms for each type. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5.

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

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

The description discloses that it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density. This adds behavioral context beyond the annotations (which already mark it read-only). Minor omission: no mention of time/rate-limit implications of multi-probe orchestration, but the annotated safety profile lowers the 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?

Three concise sentences: the first front-loads the core purpose, the second explains the mechanism and use case, and the third states the output. Every sentence contributes value with zero fluff.

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

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

Given the tool's complexity (4 params, 1 required, no output schema), the description covers the mechanism, use case, and return format ('ranked list with score, confidence, signal density'). This is sufficient for an agent to select and invoke the tool correctly, especially with fully documented schema and annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it only restates the 'first entry as subject' nuance already present in the entities parameter description. No additional parameter semantics are provided in the tool 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 is highly specific: 'Compare AI visibility across multiple entities side-by-side' clearly states the verb, resource, and scope. It also distinguishes from sibling tools by mentioning the internal use of ai_visibility_check and the ranking/surface outcome, making it unique among compare_entities and ai_visibility_check.

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 a clear use case ('competitive AI-marketing audits') and an implicit alternative ('Probes each entity with ai_visibility_check' suggests using that tool for single-entity checks). However, it doesn't explicitly state when NOT to use this tool vs. alternatives, so it falls just 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?

Beyond the read-only/idempotent annotations, the description adds valuable behavioral context: it mentions the composite fan-out to two services, potential latency (5-30s for bundlephobia first measurement), graceful degradation with sources_failed, and the exact return structure. This is rich transparency.

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

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

The description is a single dense paragraph with high information density. It front-loads the core purpose, then details usage, returns, and failure modes. While long, every sentence earns its place; minor structural improvements could be made with bullets, but it's still effective.

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

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

Given the tool's complexity (composite sources, partial failures, latency), the description is remarkably complete. It lists all expected output fields, explains the ecosystem scope, and covers degradation behavior—everything an agent needs to invoke and interpret results 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 covers 100% of parameter descriptions (package name, version default). The description adds only minor context (NPM ecosystem limitation), but since schema coverage is full, a baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a composite check for 'should I add this npm package' combining deps.dev and bundlephobia data. It specifies exact data points (license, advisories, bundle size, etc.) and distinguishes itself from unrelated siblings by focusing on npm packages.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides an alternative for non-npm ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving clear usage boundaries.

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, the description discloses specific behavioral details: output includes character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char overlapping windows, and has a 200K character cap with truncation flagged. These are valuable operational details not captured in annotations.

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

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

The description is four sentences, each with a distinct role: core function, use case, sibling integration, and technical behavior. It is front-loaded with the primary action and contains no filler or repetition.

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

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

Given there is no output schema, the description adequately covers return values (passages with offsets and similarity scores), limits (200K chars, truncation flag), and usage context (pairs with ask_pipeworx_grounded). It is complete enough for an agent to decide when and how 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 provides full parameter descriptions with examples and constraints, so the description adds little extra parameter-level meaning. It reinforces the 'text' parameter's purpose as pre-fetched content, but that is already implied by the schema 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 'Semantic search INSIDE a fetched record' with a specific verb and resource, and differentiates from siblings by focusing on pre-pulled text rather than the whole document. It also names the output (top-N passages with character offsets and similarity scores), making the purpose unmistakable.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt' and describes how search_within 'saves context,' returning only relevant passages. It also provides an alternative workflow by pairing with ask_pipeworx_grounded, giving clear when-to-use and integration 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?

The description contradicts the idempotentHint annotation. It states 'Returns the new subscription id,' implying each call creates a new subscription, while the annotation marks the operation as idempotent. Although the description discloses auth requirements, phone verification, and delivery limits, the contradiction is a serious issue.

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

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

The description is lengthy but front-loaded with the main action and return value, then organized by subscription type and delivery channel. Every sentence provides useful guidance, and the structure improves scannability.

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

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

Given the tool's complexity and lack of output schema, the description covers return value, all subscription types with examples, delivery options, auth requirements, phone verification, webhook signing, and rate limits. It provides a complete picture 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 schema has 100% coverage, and the description enriches parameter meaning with concrete examples (e.g., sec_8k items like '5.02', polymarket_edge topic 'fed', fred_series series_id 'UNRATE'). It also explains the delivery object's sub-parameters and constraints (e.g., phone verification, 10/day cap, webhook auto-disable).

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 with a specific verb ('Create a proactive monitoring subscription') and resource ('live-data event stream'), and explicitly mentions the return value ('Returns the new subscription id'). This distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context on when to use the tool (for proactive monitoring) and includes prerequisites (Pipeworx OAuth account) and supported types/delivery channels. It does not explicitly contrast with alternatives, but the use case is well-defined.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds meaningful context beyond annotations: it returns example questions with tool+argument shape from the live catalog, supports optional topic filtering, and describes the fallback behavior when no arguments are passed.

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

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

The description is long but well-structured, front-loading user-phrase triggers and then delivering purpose, return content, and usage. Each sentence earns its place; the length is justified by the tool's onboarding role and the need to explain the categorized output and optional filtering.

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 the lack of an output schema, the description fully explains what the tool returns (category-bucketed example questions with exact tool+argument shape) and how to invoke it. Combined with the clear annotations and complete parameter documentation, the description is sufficient for an agent to select and call 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% for the single `topic` parameter, with an enum-like description. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and explaining the omission behavior ('Omit for a cross-category spread'), which goes beyond the schema's static text.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings by explicitly positioning it as the first tool to use when unfamiliar with Pipeworx, and its scope ('what can I ask?') is unique.

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

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

Explicit guidelines are provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains how to call it with or without the `topic` parameter, and mentions learning meta-tools, which clarifies when to prefer this over alternatives like ask_pipeworx.

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

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

Adds key behavior beyond annotations: deactivation rather than deletion, and the impact on recent_alerts. The annotation already marks non-destructive and idempotent, but description enriches with consequences.

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 crisp sentences, action-first, with no filler. Each sentence adds essential information (ownership, deactivation effect).

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, the description covers purpose, constraint, and side-effect. Combined with thorough schema and annotations, it's complete and well-contextualized.

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 fully documents the only parameter id, including its source ('returned by subscribe'). Description adds no further parameter detail, matching the baseline for high 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?

States 'Cancel a subscription by id' with a specific verb and resource. The ownership and deactivation details clarify scope, distinguishing it from subscribe/list_subscriptions.

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

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

Implies usage context as the cancellation counterpart to subscribe, and notes the ownership restriction (only your own subscriptions). However, it doesn't explicitly compare with alternatives or state when not to use.

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

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

Annotations already cover read-only/open-world/idempotent, but the description adds substantial context: routing to SEC EDGAR vs grounded pipeline, the full verdict set, the crucial caveat that could_not_verify is not evidence, and what unsupported means. This goes well 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?

Although long, every sentence earns its place: trigger phrases, routing logic, return values, caveats, and efficiency note. It is front-loaded with natural-language triggers and well-structured 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 compensates by listing verdict enum values, explaining error and unsupported semantics, and describing the citation format. It covers all necessary usage contexts, 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 extra meaning for tolerance_pct (overrides implied tolerance, suggests 1–2 for hallucination detection) and gives concrete examples of claim, enhancing understanding beyond schema descriptions.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It gives specific verbs like 'fact check', 'verify', 'confirm or refute' and distinct scopes (company financials vs other facts), distinguishing it from sibling Q&A 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?

It explicitly says when to use: 'whenever the agent needs to check whether something a user said is factually correct.' However, it does not mention when NOT to use it or point to alternatives, so it lacks explicit exclusions or alternative recommendations.

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