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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these annotations: it routes to 5,529 tools across 1,455 sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes one fast call. It also hints at a trade-off by contrasting with ask_pipeworx_grounded, implying this tool prioritizes speed over verbatim evidence. No contradiction with annotations.

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

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

The description is long but front-loaded with the most critical directive (PREFER OVER WEB SEARCH) and follows a logical structure: scope, capabilities, when to use, examples, escalation paths. While every sentence adds value, the length approaches verbosity; however, given the complexity of the tool, it remains readable and well-organized. Minor redundancy (e.g., "START HERE" repeats the preference) prevents a 5.

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

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

Given the tool's broad scope and the absence of an output schema, the description is remarkably complete. It explains what the tool does, the types of questions it handles, what it returns (structured answers with citation URIs), its operational characteristics (works on every tier, fast single call), and when to use alternatives. This is more than 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?

Schema description coverage is 100%: all six parameters are aliases for the single 'question' field and each has a clear description. The tool description itself does not add parameter-level detail, but since the schema fully documents the aliases and the natural-language input, no compensation is needed. The baseline of 3 applies here because the description adds no extra meaning beyond the schema.

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

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

The description clearly states the tool's function: it routes factual questions to a wide array of authoritative sources and returns structured answers with citations. It explicitly lists example domains (SEC filings, FDA data, FRED/BLS, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its unique role clear.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and continues with 'START HERE' as the default entry point. It gives concrete when-to-use guidance (e.g., "what is", "look up", "get the latest") and explicit alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. This is exemplary usage guidance with named alternatives and conditions.

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

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

Discloses the experimental edge, live candidate routing improvements, that results are compared against the stable router, and that it is a full working router with no fallback. Complements annotations (readOnly, openWorld, idempotent) by adding operational context; no contradiction.

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

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

The description is front-loaded with beta status and each sentence adds meaningful context, though it is somewhat wordy in enumerating tool counts and timing details. Overall efficient for the complexity it covers.

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

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

Covers purpose, usage, experimental status, and relationship to the stable sibling. Despite lacking an output schema, it specifies the same response shape as ask_pipeworx, making it complete for an agent familiar with the sibling tool.

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

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

The input schema already provides 100% coverage with descriptions for every alias and the main question parameter. The description does not add parameter-specific details but references identical arguments as ask_pipeworx, which is adequate given schema completeness.

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

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

The description clearly states it is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes from the stable sibling by highlighting experimental routing improvements and current inactive candidate status.

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

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

Explicitly instructs to use exactly like ask_pipeworx when wanting the newest routing, and notes that no candidate is active currently so it matches stable behavior. This gives clear when-to-use guidance and implicitly contrasts with the stable router.

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 well beyond the annotations by detailing the exact return shape on success and the explicit refusal reasons on failure (e.g., 'not_in_source', 'no_tool_match'). It also discloses the additional LLM call cost and the guarantee that answers are grounded solely in tool results, providing rich 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 front-loaded with the core purpose in the first phrase. Every sentence provides value: mechanics, return format, usage scenarios, and cost comparison. No wasted words, and the structure flows logically from what → how → when → tradeoff.

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

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

Given that there is no output schema, the description appropriately covers return values and refusal reasons in full. It also explains the tool's internal routing complexity, when to use it, and the cost difference from the alternative, making the description complete for an AI agent to make an informed 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 schema covers 100% of parameters (all aliases for 'question'), so the description adds no new parameter-level semantics. The baseline of 3 applies because the schema fully documents the parameter and its aliases; the description's mention of 'fills arguments' is about internal routing, not the parameter itself.

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 is a 'Hallucination-resistant answer mode for high-stakes reads' and explains it 'EXTRACTS the answer using ONLY what the tool result contains.' This specific verb+resource framing distinguishes it from the sibling ask_pipeworx, which is described as the casual alternative.

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 this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives an exclusion: 'prefer ask_pipeworx for casual lookups,' and mentions the cost tradeoff ('Costs one extra LLM call').

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 mark the tool readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context: account and paid-tier requirement, parallel routing, gap reporting (gaps[]), no invented findings, contradictions[] for standard/thorough, citation_uri semantics, semantic excerpting, and latency expectations. 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 dense and front-loaded with the account requirement, using semicolons and parentheses to pack information efficiently. It is somewhat lengthy due to the tool's complexity, but contains some redundancy (e.g., contradictions[] mentioned twice, NOT open-web search repeated in behavioral details). Overall well-structured and every sentence adds value.

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

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

With no output schema, the description must explain return values, and it does: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding', plus gaps[], contradictions[], and hop field. It also covers latency, citation fetchability, and excerpting, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds meaningful context beyond the schema by explaining depth behaviors: 'standard' re-angles unanswered gaps, 'thorough' chases leads, and quick/standard/thorough dictate facet counts (3/5/8). This goes beyond the schema's enum descriptions, enriching parameter meaning.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources', decomposes questions into facets, routes them to 5,529 tools in parallel, and returns a findings packet. This distinguishes it from siblings like ask_pipeworx (single lookup) and validate_claim, and the verb 'research' plus resource scope makes 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?

Explicit usage guidance is provided: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also gives news-specific guidance ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx') and notes the account requirement and fallback for signed-out users.

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 already declare readOnlyHint, idempotentHint, and non-destructive. The description adds substantial behavioral detail: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF, soft-fails on the sunset USPTO API, uses a GDELT→GNews fallback, and returns exact fields. It also notes the limitation on names and the need to zero-pad CIKs, enriching beyond the structured annotations.

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

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

The description is a single dense block but front-loaded with triggers ('Tell me about X' / 'research Acme') and the core statement of purpose. Every sentence adds detail, though some redundancy with the schema (e.g., names not supported) could be trimmed. Overall it is structured and effective, but not maximally concise.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It enumerates all returned components (CIK, filings with URIs, fundamentals sorted by period, patents, news fallback, LEI), explains source behavior (USPTO sunset, GDELT→GNews), and specifies input constraints. This fully equips an agent to invoke it correctly 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 description coverage is 100%, and the schema already explains both parameters (type enum with 'company', value with ticker/CIK examples and the name limitation). The description mostly mirrors this, though it adds a concrete example ('Pass ticker "AAPL" or zero-padded CIK "0000320193"'). With full schema coverage, baseline is 3; no significant extra parameter-level meaning is added.

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: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs like 'profile' and 'brief me on,' and distinguishes itself from siblings by naming the concrete output (cik, filings, fundamentals, patents, news, LEI). This makes it unambiguous and differentiates it from tools like resolve_entity or compare_entities.

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This nails both when to use and when not to use, with a named alternative.

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

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

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?

The description goes far beyond the annotations (readOnlyHint, idempotentHint) by detailing behavioral nuances: compatibility_warning triggers, skipped_cross_type/subtype reasons, temporal alignment semantics, and the caveat that pre-mapped ≠ tradeable. This provides exceptional transparency about edge cases and failure modes, making it a 5.

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

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

The description is lengthy but well-structured, with clear organization around modes, response format, safety fields, and warnings. Every sentence contributes meaningful information, and the front-loading of the main purpose helps. It is verbose, but given the tool's complexity and lack of output schema, the length is justified. A tighter summary could improve it slightly.

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

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

Since there is no output schema, the description fully specifies the response structure: venue leg-by-leg prices, matched spread with top_spreads_pp, and safety fields. It also covers edge cases (incompatible bet shapes, temporal misalignment) and limitations, making it complete for an agent to understand behavior 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?

The input schema already describes all three parameters with examples and formatting. The description adds semantic value by explaining the two modes (topic auto-fetch vs explicit override) and the hierarchical relationship between parameters (overrides). While schema coverage is 100%, the description clarifies when to use each parameter, adding meaning beyond the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It is specific about the resource (two prediction markets) and the operation (computing spread), and the distinct modes (topic vs explicit) differentiate it from sibling tools like polymarket_arbitrage.

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

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

The description explains both usage modes (topic shortcuts vs explicit tickers) and provides clear when-not-to-use guidance via compatibility warnings and temporal alignment checks. It explicitly notes that most pre-mapped topics are not tradeable, warning against blind use. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edges, so it falls slightly short of a 5.

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

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

Annotations already declare readOnlyHint, 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?

Beyond the readOnlyHint and idempotent annotations, the description discloses valuable behavioral traits: it cascades through several lookup endpoints internally, degrades gracefully when GLEIF or OpenFIGI is unavailable, and explicitly reports unresolved identifiers under 'unresolved' rather than omitting them. This provides the agent with expectations about network dependencies and failure modes.

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, starting with real-world queries, then a concise purpose statement, followed by detailed supported types and fallback behavior. Some repetition of schema param details exists, but the examples and structured breakdown make it scannable and information-dense without being wasteful.

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

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

Despite lacking an output schema, the description thoroughly explains what will be returned for each type, including source attribution, ownership data, and unresolved identifiers. It also covers graceful degradation and internal cascading, making the tool's behavior predictable for an agent even without structured output definitions.

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 significant meaning to the 'type' parameter by explaining what each type returns (company vs. drug) and what inputs are accepted (ticker, CIK, name for company; brand/generic for drug). This goes beyond the schema's terse descriptions and helps the agent construct valid values.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific verbs like 'resolve' and 'look up' and a clear resource (entities). It distinguishes itself by emphasizing it is the first tool to use when you have a name but need an ID, and its supported types are explicitly laid out, separating it from sibling tools like entity_profile and 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 says 'Use FIRST whenever you have a name but need an ID,' which gives clear guidance on when to invoke this tool. It does not explicitly mention alternatives or when-not-to-use scenarios, but the context is strong enough to guide selection among the sibling tools.

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

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

The description 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.