advice

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations, including the default model (Workers AI free), the BYO key cost implication (you pay Anthropic directly), and the response structure. No contradiction found.

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 primary purpose, and every clause carries relevant information. 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?

Despite having no output schema, the description explains the return shape ('per-model {score, confidence, signals, raw_response} + a combined view') and covers defaults, cost, and use cases. Minor ambiguity about what 'signals' means, but not critical for invoking 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%, so the baseline is 3. The description adds some nuance (default model, BYO key cost) but does not substantially enhance per-parameter semantics beyond what the schema already provides.

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

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

The description clearly states a specific action ('Probe one or more LLMs') with a defined output ('score visibility (0-100) per model'). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on LLM knowledge of an entity rather than competitor scanning.

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

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

Provides clear context for when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to infer appropriate use cases.

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 valuable context about internal routing (5,366 tools, 1,396 sources), return format (structured answer with pipeworx:// citation URIs), and performance (works on every tier, one fast call). It does not contradict annotations and provides meaningful behavioral details beyond them.

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

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

The description is longer than average but well-structured, starting with a strong directive ('PREFER OVER WEB SEARCH') and then clearly laying out usage, alternatives, and examples. Some repetition exists (e.g., multiple 'use when' statements), and the exact tool count is non-essential, but each sentence contributes to the overall guidance. It is appropriately sized for a tool with many siblings and usage nuances.

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

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

Despite no output schema, the description explains the return value (structured answer with citation URIs) and covers usage scope, alternatives, and performance. The tool is simple (one required parameter) and the description fully equips an agent to decide when and how to invoke it, including edge cases like news queries. It is complete for its complexity level.

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 with descriptions for all six parameters, all of which are aliases for the same `question` string. The description adds examples and trigger phrases ('what is', 'look up', 'find'), but does not introduce new parameter-specific semantics. Since the schema already documents the parameter thoroughly, 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 question-answering router that queries 5,366 tools across verified sources. It explicitly differentiates from siblings by referencing ask_pipeworx_grounded and deep_research, and provides concrete examples of supported domains (SEC filings, FDA data, FRED/BLS, etc.). The verb+resource is unambiguous: 'ask' for factual 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 gives explicit when-to-use guidance ('Use whenever the user asks...', 'START HERE for most questions') and when-not-to-use alternatives ('Step up only when needed: for ... use ask_pipeworx_grounded; for a broad/multi-part question ... use deep_research'). It also clarifies edge cases like breaking news. This is exemplary 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 cover readOnly, openWorld, idempotent, and non-destructive traits. The description adds valuable behavioral context: it is an experimental edge with live candidate routing improvements, currently no candidate active, and outputs are compared against the stable router. This goes beyond annotations by explaining the beta status and comparison behavior, though it doesn't detail response structure beyond 'same response shape' (which is adequate given sibling reference).

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

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

The description is a single paragraph of about five sentences, front-loaded with the key fact ('Beta version') and then explaining current status and use case. There is minor redundancy ('this currently matches ask_pipeworx exactly' near 'this IS a full working router'), but overall it is efficient and well-organized for the tool's complexity.

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

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

Given the tool's complexity (universal router with 5,366 tools) and absence of output schema, the description provides sufficient context: it names the stable sibling for reference, clarifies the experimental nature, and states response shape is identical to ask_pipeworx. This is enough for an agent to invoke it correctly, though it could mention potential behavioral differences during candidate tests.

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

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

Schema description coverage is 100% with all six parameters (question and five aliases) documented in the schema. The description adds no new parameter-level semantics; it only states 'same arguments' as ask_pipeworx, which is a redundant pointer. Baseline 3 is appropriate since the schema fully covers parameter meanings.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with 5,366 tools, and explicitly distinguishes it from the stable ask_pipeworx sibling by emphasizing its experimental edge. The verb 'use' and resource 'pipeworx_beta' are specific, and the phrase 'this IS a full working router' removes ambiguity about its function.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear when-to-use instruction. It also contrasts with the stable router ('results are compared against the stable router to decide what merges') and notes the current state (matches ask_pipeworx exactly), effectively guiding selection among 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?

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. Description adds rich behavioral context: it returns a structured refusal with specific refusal_reason values when data doesn't directly answer, and it explicitly limits answer extraction to tool result contents, protecting against hallucination.

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?

Though longer than average, every sentence earns its place: mode definition, process, return shape, refusal modes, use cases, and cost tradeoff. It is front-loaded with the key differentiator and structured logically, making it easy to scan.

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

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

For a tool with no output schema, the description fully specifies return shape on success and failure, enumerates refusal reasons, names the cost tradeoff, and gives concrete high-stakes use cases. This 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?

Schema description coverage is 100%, with clear aliases documented for the single required question parameter. Description adds no parameter-level detail beyond schema, but schema fully covers the semantics, so baseline 3 is appropriate.

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

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

Description clearly states this is a hallucination-resistant answer mode for high-stakes reads, with a specific verb+resource and explicit differentiation from sibling ask_pipeworx. It says it EXTRACTS answers using only tool result contents, making its unique value unmistakable.

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

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

Explicitly states when to use: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, with examples. Also provides an alternative: prefer ask_pipeworx for casual lookups, noting the extra LLM call cost.

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 readOnly/idempotent annotations, the description discloses many behaviors: parallel fan-out, resolver contract with confidence fields, safety short-circuiting for low-confidence matches, closed-market status, wide-spread illiquidity flag, and cancellation-rule parsing. This far exceeds the annotation baseline.

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 highly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the core purpose and use cases, and while extensive, the detail is useful for a complex tool. Slight verbosity 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?

With no output schema, the description compensates comprehensively by describing result shapes, resolver contract, parent event extractor, news fields, and safety mechanisms. It also covers edge cases (closed markets, low-confidence matches) and resolution-rule risk, making it fully 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 input schema already provides full descriptions for all three parameters (coverage 100%), with market format, depth defaults, and include_raw semantics. The description adds examples (URLs and slug formats) but mostly repeats the schema content, so it stays at the baseline of 3.

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

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

The description opens with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It then lists explicit use cases ('should I bet on X', etc.) and includes classifiers, which distinguishes it from generic research tools and other Polymarket-specific siblings.

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

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

The description provides explicit usage context with the 'Use for' list and examples ('BTC bet → coingecko + fred...'), telling the agent when the tool is appropriate. It does not explicitly name alternative tools for exclusions, but the context is clear enough for a 4.

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

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

Despite annotations already indicating read-only, idempotent, and non-destructive behavior, the description adds meaningful context: specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. 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 but every sentence adds value: trigger phrases, capability, data specifics, sorting behavior, and output format. It is front-loaded with the most important usage context and remains focused throughout.

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 2 parameters and no output schema, the description fully covers inputs, behavior, and output expectations. It explains the return format (paired data + citation URIs) and the sorting by primary metric, 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 enriches parameter meaning by describing what each type pulls (revenue, net income for company; adverse-event counts, FDA approvals for drug) and how values map (tickers/CIKs vs names). This goes beyond the schema's brief field descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases like 'X vs Y' and 'which is bigger'. It distinguishes itself from sequential lookups by emphasizing preference over them.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', along with concrete example queries. It also explains what it replaces (8–15 sequential lookups), making the choice 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?

Even with annotations readOnlyHint/openWorldHint/idempotentHint, the description adds substantial behavioral detail: account requirements, parallel facet decomposition, the findings packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), gaps[] never invented, hop/citation_uri fields, contradictions[], semantic excerpting, and latency expectations. 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 information-dense. It front-loads the account prerequisite, then core purpose, usage boundaries, and behavioral details. Every sentence earns its place, covering auth, alternatives, return format, limits, and timing without filler.

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

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

With no output schema, the description fully explains what the tool returns: findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and hop fields. It also covers prerequisites, decomposition, iteration behavior, excerpting, and expected latency, making it complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by clarifying that 'question' can be broad/multi-part ('Decomposes your question into focused facets') and by elaborating the practical implications of depth values ('standard' re-angles gaps; 'thorough' chases leads), which supplements the schema's enum descriptions.

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

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

The description immediately identifies the tool's specific function: 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources ... in ONE call'. It clearly distinguishes itself from open-web search and from sibling ask_pipeworx, making its purpose unmistakable.

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

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

The description gives explicit usage direction: 'Best for broad/multi-part questions over structured data', and clear alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. These when/when-not guidelines are exemplary.

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 the safety profile. The description adds valuable behavioral context: returns top-N relevant tools with full input schemas and curated examples, ready to call directly without a second lookup. It goes beyond annotations by describing the return format and direct callability.

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: first sentence defines purpose, second gives usage context, third explains return behavior, fourth gives strategic guidance. Every sentence earns its place, with no redundancy. Front-loaded with the action verb and resource.

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

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

Despite having no output schema, the description fully explains what the tool returns (names, descriptions, schemas, examples) and why it is useful. Combined with the rich annotation set, the description is complete for a meta-tool with 6 params and many aliases.

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

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

Schema description coverage is 100%, with every parameter (including aliases) documented. The description itself doesn't add further parameter semantics; it mentions 'describing the data or task' but relies on the schema's examples. Baseline 3 is appropriate since structured data does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many domains (SEC filings, FDA drugs, FRED data, etc.) and explicitly distinguishes itself as a meta-tool: 'Call this FIRST when you have many tools available.' This is a specific verb+resource with clear differentiation 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?

Explicit usage guidance is provided: '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 (not just one answer).' It communicates when to use the tool and implies when not to (when you already know the specific tool).

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

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

The description adds rich behavioral context beyond the readOnlyHint and idempotentHint annotations: it fans out to multiple sources, soft-fails on USPTO PatentsView API sunset, uses GDELT→GNews fallback, and returns structured data. These details disclose internal behavior and failure modes, which is valuable for an agent.

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 every sentence earns its place: it opens with relatable examples, states the core action, provides usage preference, enumerates data sources and return fields, and closes with input format constraints. Well-structured and front-loaded.

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

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

With no output schema, the description thoroughly covers what the tool returns: CIK, company_name, recent_filings with URIs, fundamentals, patents, news, and LEI. It also covers limitations, fallbacks, and edge cases, 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% with detailed descriptions for both parameters, including examples and the note that names are not supported. The description repeats this information without adding new semantic value, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It includes example user phrasings and distinguishes itself from siblings by noting it should be preferred over chaining single-pack SEC/XBRL/news lookups for holistic views.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'names not supported (use resolve_entity first if you only have a name).' This clearly states when to use the tool and which alternative to use for unsupported inputs.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the deletion behavior is covered. The description adds context about clearing sensitive data and addressing stale context, which goes beyond annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the core action, and every word earns its place. It elegantly communicates purpose, usage, and related tools without any redundancy.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description fully covers its purpose, usage, and relationships to sibling tools. Annotations handle safety aspects, so the description is complete for effective tool selection and invocation.

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

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

The schema covers the only parameter 'key' with the description 'Memory key to delete' at 100% coverage. The tool description does not add additional parameter semantics beyond what the schema 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 opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly differentiates it from sibling tools 'remember' and 'recall' by indicating deletion, storage, and retrieval respectively.

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 when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This gives clear conditions for use, and 'Pair with remember and recall' suggests related 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that the tool fetches the page, extracts metadata and links, outputs a single text blob in standard llms.txt markdown, and states it is ready for deployment. This provides meaningful context beyond the annotations, especially the exact output format.

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

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

The description is three sentences, front-loaded with the main action, and efficiently covers the process and use cases without any wasted words. It is appropriately 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?

With only two parameters, no output schema, and annotations covering safety, the description provides a solid overview including output format and placement. It could mention error cases, but for this scope it is sufficiently complete, earning a 4.

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 100% coverage with clear descriptions for both parameters (url and max_links). The tool description does not add additional parameter-level details beyond what the schema already specifies, 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 generates an llms.txt file for any URL, detailing the process of fetching the page and extracting title/description/key links. It also lists specific use cases (client indexing, personal drafting, competitor auditing), which distinguishes it from siblings even if some overlap in the auditing aspect.

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 three explicit use cases and explains the tool's role in getting sites indexed by AI crawlers. However, it does not explicitly mention alternatives or when not to use the tool, only clear context, which aligns with a score of 4.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it 'returns the full advice text', which clarifies the output behavior—a useful addition for a simple read 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 two concise sentences with the verb and resource front-loaded. Every piece of information is relevant, and there is no redundancy or unnecessary detail.

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 and an output schema available, the description covers the tool's purpose, the parameter usage, and the return value. There are no missing details or ambiguities for this simple 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 fully documents the 'id' parameter as a numeric ID with a clear description, and the description reiterates this with an example. Since schema coverage is 100%, the description adds minimal extra semantic value, though the example is helpful.

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

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

The description uses the specific verb 'Get' with resource 'specific advice slip by numeric ID', and includes an example ID (42). This distinguishes it clearly from sibling tools like random_advice and search_advice, which have different purposes.

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 use when a known numeric ID is available, but it does not explicitly mention alternatives or exclusions. However, the sibling tool names provide clear context, so the usage scenario is clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations by specifying the return format (fields) and the scope ('caller's active subscriptions'), which helps the agent understand what to expect.

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 and front-loaded with the primary function, followed by return fields and usage guidance. Every sentence contributes meaningful information with no repetition or filler.

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 simple with one optional parameter and no output schema. The description fully covers the return fields, default behavior (active subscriptions), and a practical use case. Given the rich annotations and small schema, nothing critical is missing.

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

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

Schema description coverage is 100% for the single parameter include_inactive, so the schema already explains its meaning. The description does not add further syntax or format details beyond what the schema 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's function with a specific verb and resource: 'List the caller's active subscriptions.' It also lists the exact fields returned (id, type, params, etc.), distinguishing it from subscribe/unsubscribe and other sibling tools. The additional guidance about reviewing subscriptions before adding more reinforces its purpose.

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

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

The description provides explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool. It doesn't explicitly name alternative tools like unsubscribe, but the context is clear enough for a list operation.

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?

Although annotations provide no hints (all false), the description discloses key behavioral traits: rate limit ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and impact ('signal directly affects roadmap'). It does not mention response behavior or of data handling, but these are less critical for a feedback 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 longer than strictly necessary but every sentence provides distinct value: purpose, usage scenarios, content guidance, team impact, rate limit, and quota. It is front-loaded with the main purpose and organized logically, though it could be tightened.

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

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

The description covers purpose, usage, constraints, and operational details (rate limit, cost). It does not explicitly mention the optional context parameter, but that is fully documented in the schema. Given no output schema, return values are not needed. Overall, it is complete for a simple feedback tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and elaborates on the categories (bug, feature, data_gap, praise) with examples, enriching the semantics beyond the schema's enum descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource (Pipeworx team), and distinguishes itself from siblings by focusing on feedback submission, not data retrieval or analysis.

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

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

The description explicitly lists when to use the tool: '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 provides guidance on what to include, such as describing the issue in terms of tools/packs, which is clear and actionable.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable context: derived from CF analytics-engine, no PII, output shape '(pack, tool, count)', and caching behavior (5min-1h). This goes beyond annotations.

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

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

Well-structured: a one-sentence summary, a bulleted list of use cases, and a final sentence on data provenance and caching. Every sentence earns its place; purpose is front-loaded.

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

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

For a simple one-optional-param tool with no output schema, this is comprehensive. It covers purpose, use cases, output contents, privacy, and caching, giving the agent enough to select and invoke correctly.

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

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

Schema coverage is 100%, with the window parameter fully described (enum values, default, meaning). The description repeats the window options but adds no new parameter-level semantics; the caching note is behavioral, not param-specific.

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 shows what other AI agents are calling on Pipeworx, returning top tools, top packs, and call volume. The verb 'Returns' is specific, and the focus on aggregate usage distinguishes it from siblings that search or give advice.

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 three explicit use cases: discovering hot data sources, confirming canonical choice, and aligning use case. Clear context but no explicit exclusions or alternative tool references, though the use cases imply when it's useful.

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 detailed internal behavior: Jaccard similarity threshold (≥0.30), placeholder filtering (>20% returns null), fill check against live CLOB depth, and >3pp deviation threshold for signals. These specifics go well beyond the annotations (readOnly, openWorld, idempotent) and give the agent a precise model of tool execution.

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

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

The description is long but well-organized with capitalized section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and no filler sentences. Each clause adds operational detail, and the core purpose is front-loaded, making the length justified.

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

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

With no output schema, the description fully explains return values (opportunities[], partition_check{}, gap_pp, suggested_trade, reasoning) and edge cases (thin_legs, realizable_edge_pp ≤ 0). It also cross-references polymarket_fill_risk for custom sizing, completing the operational context.

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

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

While the schema already documents both parameters (100% coverage), the description adds substantial meaning: examples of event slugs, behavior with no args (trending_scan), how topic works across events, and acceptance of full Polymarket URLs. This enriches the bare schema definitions significantly.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' clearly stating the tool's verb, resource, and method. It distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_fill_risk, making purpose unambiguous.

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

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

The description provides explicit 'Call with NO args...' instructions and recommends when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It also directs users to polymarket_fill_risk for custom sizing and warns not to trade when realizable_edge_pp ≤ 0, offering clear when-to/not-to-use context.

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

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

Annotations already mark it read-only and non-destructive, but the description goes well beyond by detailing output segments, edge calculations, Kelly capping, per-leg favorite-longshot bias corrections, caching at 1h, and the 24h-move warning. It also exposes diagnostic counters (_diagnostics) so callers can see why segments are empty, 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 long but well-sectioned with model families, knobs, and top-level response structure. It is front-loaded with the core purpose statement, but the dense all-caps and parenthetical details could be more scannable; still, every sentence contributes 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?

With no output schema, the description compensates exceptionally by specifying the top-level by_segment structure, fed_candidates/fed_note reasoning, and _diagnostics fields. It also covers caching, model gates, and slippage assumptions, making it remarkably complete for a complex tool with 9 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful layer by explaining the 'TRADEABLE-EDGE KNOBS' and clarifying the special behavior of min_kelly for partition arbs (kelly_fraction_half=0 at parent level). This helps agents decide when to adjust parameters, so a 4 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?

Description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' — a specific verb, resource, and outcome. It further distinguishes itself with the target use case ('what should I bet on today') and names three model families, clearly separating 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?

It explicitly frames the tool as 'Built for "what should I bet on today"' and explains when knobs like min_liquidity/max_spread_pp should be used. However, it does not name alternative tools or state explicit when-not-to-use scenarios, so it earns a 4 rather than 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 goes well beyond the annotations by disclosing data availability nuances: snapshots are only written on cache-miss, so gaps mean no scan happened; history is bounded by a 60-day TTL; decay is computed from daily closes (not intraday). These are non-obvious behavioral traits that affect interpretation. The annotations indicate read-only and non-destructive, which the description fully supports, with 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 substantial but every sentence earns its place: it starts with purpose, explains parameters inline, details the response structure (tracked, expired, snapshot_dates), and ends with limitations. It is front-loaded with the core question and logically organized, with 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 fully compensates by enumerating the response fields (`tracked[]`, `expired[]`, `snapshot_dates[]`) and their meanings. It also covers data history limits, gap behavior, and calculation basis. For a telemetry tool with moderate complexity, this is complete and self-sufficient.

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

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

The schema already documents both parameters with descriptions and defaults, and the description mostly restates them (e.g., 'days (lookback, default 14, max 30)' mirrors the schema's 'Lookback in days (default 14, clamp 2-30)'). It adds a little context by calling window a 'snapshot family,' but this is marginal. Since schema coverage is 100%, the baseline is 3 and the description does not significantly raise 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 opens with a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes itself from related tools like polymarket_edges by focusing on 'how long has this edge existed and is it shrinking?' This makes the purpose unmistakable and differentiates it from sibling tools that likely return current edges or arbitrage opportunities.

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 for when to use the tool: to answer whether an edge is persistent or decaying, and to compare fresh versus old edges. It even gives a practical framing: 'the median lifespan is your competition clock.' However, it does not explicitly name alternative tools or 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?

Despite annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds rich behavioral context: it walks the order-book ladder, explains partial fill risk, describes per-leg detail, thin legs, forced directional risk, and warns about the dominant loss mode (unhedged directional positions). 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?

Although dense, every sentence earns its place. The description is front-loaded with the core purpose, then structured into SINGLE-MARKET and BASKET sections, specifying defaults, return fields, and risks. No filler; length is proportional to the tool's complexity.

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

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

For a tool with no output schema and high complexity (two modes, multiple return fields, edge risks), the description fully covers use cases, parameter behavior, return values, and failure modes. It even names the 'dominant loss mode,' which is exceptional contextual depth.

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

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

Schema covers all four parameters with descriptions, but the tool description adds vital semantics: the conditional requirement of market vs event, the different interpretation of size_usd in single-market vs basket mode, and how side defaults vary. This goes well beyond the schema's parameter descriptions.

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

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

The description opens with a specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes from sibling tools by naming polymarket_arbitrage and polymarket_edges directly. It also explains two modes (single-market and basket), making the tool's scope unambiguous.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also describes when each mode (single-market vs basket) applies and the side semantics, providing clear decision guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes far beyond that by disclosing response structure (leg-by-leg prices, spread[].top_spreads_pp), safety fields (compatibility_warning with two distinct cases), temporal_alignment semantics, and skipped_cross_type/subtype counters. It even reveals that many pre-mapped topics return warnings today. This is exemplary behavioral transparency with no contradiction to annotations.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds useful information about behavior, response, or caveats. While it is verbose, the complexity of the tool justifies the length. It's front-loaded with the core purpose and then details. The structure makes it scannable, though it could be tightened slightly without losing value.

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

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

With no output schema, the description fully compensates by detailing the response format, including safety fields and their meanings. It covers edge cases (matched_pairs:0, temporal misalignment), and explains the skip counters. For a tool with complex matching logic and important caveats, this description is highly complete, giving an agent everything needed to interpret results and avoid misuse.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds meaningful semantics by explaining the two modes: `topic` is a pre-mapped shortcut that auto-fetches matching events, while explicit `kalshi_event_ticker` and `polymarket_event_slug` override the topic-mapped side for custom pairings. This clarifies the interplay between parameters beyond the schema's individual descriptions. It doesn't provide format restrictions (beyond examples) but compensates well.

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

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

The description opens with a clear, specific statement: "Cross-venue spread between Kalshi and Polymarket for the same resolving question." It specifies the exact resource (spread between two named venues) and verb (compute/return spread), distinguishing it from sibling tools like polymarket_arbitrage which focus within a single venue. The two modes (topic shortcuts vs explicit ticker/slug) further clarify 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 strong usage context: it explains when the spread is a real signal (equivalent bet shapes) and when it isn't (compatibility_warning). It also sets expectations that most pre-mapped topics are not tradeable. However, it does not explicitly name alternative tools or state 'use this when you need cross-venue spreads,' so it lacks explicit exclusions. Still, the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnly and non-destructive hints. The description adds the 'random' behavior (not captured in annotations) and explains the purpose of the slip ID for follow-ups, which goes beyond 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?

Single sentence, front-loaded with the action, no redundant information. Every clause adds value: the random nature, what is returned, and the purpose of the ID.

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 parameters and a simple output (advice text + slip ID), the description fully explains the tool's behavior and result. Annotations cover safety, and the output schema exists, so no further details are needed.

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

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

There are zero parameters, so the description needs no parameter explanations. Schema coverage is vacuously 100%. The baseline for 0 params is 4, and the description appropriately focuses on output rather than inputs.

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

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

The description uses a specific verb ('Get') and resource ('random piece of advice'), clearly distinguishing it from siblings like get_advice and search_advice. It also states the return value (advice text and slip ID), reinforcing purpose.

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

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

The word 'random' and the reference to 'follow-up queries' imply the intended use case (e.g., discovery or inspiration) and how to use the slip ID later. It does not explicitly mention alternatives or exclusions, but the context is clear enough for a simple tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, reducing the burden on the description. The description adds valuable context beyond annotations: scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving versus listing all keys. It does not mention error handling for missing keys, but with strong annotations and disclosed behavior, this is sufficient.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds value without repetition. It is concise and well-structured, avoiding fluff and 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?

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, scoping, interactions with related tools, and the omit-key behavior. It is complete enough for an agent to invoke the tool correctly without 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?

Input schema descriptions cover 100% of parameters (the 'key' field is described), so the baseline is 3. The description enriches the parameter meaning by tying it to the remember tool and emphasizing that omitting the key lists all saved keys, adding context beyond the schema's terse description.

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

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

The description clearly states the tool retrieves a value saved via remember, and distinguishes two behaviors: retrieving a specific key or listing all keys when the key is omitted. It also references sibling tools (remember, forget) and explains the resource (memory), making its purpose distinct.

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 context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names complementary tools (remember to save, forget to delete) and implies a non-usage condition (only for values previously saved via remember), giving clear guidance on when 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses the return payload contents (source, citation_uri, raw payload), the side effect of mark_read (flagging events read so future calls show only newer ones), and the caveat that citation_uri is 'pipeworx:// when available'. It also notes the feed is persisted and accessible via REST. This adds significant behavioral detail beyond the structured annotations.

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

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

The description is two information-dense sentences, front-loaded with the main action. Every clause adds value: payload details, filtering options, mark_read behavior, polling guidance, and an alternative access method. No redundant or irrelevant content.

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

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

For a read-oriented tool with 5 parameters and no output schema, this description covers the essential context: what is returned, how to filter, the mark_read side effect, polling suitability, and an alternative REST access. It is complete enough for an agent to know when and how to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by giving an example type filter ("sec_8k") and explaining the behavioral impact of mark_read on subsequent calls. It does not add much for limit or unread_only, but the schema already describes those well.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly distinguishes itself from sibling tools like list_subscriptions (which manage subscriptions) by focusing on the events fired on the feed, and mentions the evaluator's written alerts, 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?

It provides usage context by stating 'Polls work fine' and offers an alternative REST endpoint for scripts/dashboards, which serves as a when-to-use-this-vs-alternative. However, it does not explicitly mention sibling tools or state when not to use this tool, so it lacks full exclusion guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds significant behavioral context: multi-source fan-out, GDELT→GNews fallback on rate limits/5xx, USPTO PatentsView sunset soft-fail, and output structure (changes[] grouped by source, total_changes, citation URIs). 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 yet efficient, with every sentence serving a purpose: examples, source behavior, parameter formats, output summary, and cross-reference to entity_profile. It is front-loaded with user query patterns, making it immediately understandable without excess.

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

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

Despite no output schema, the description specifies the return shape ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It covers fallback sources, edge cases, and the alternative tool, making it complete for a complex multi-source 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 covers all parameters with descriptions, but the description enhances semantics by specifying accepted value formats: `since` accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y'), `value` is a ticker or zero-padded CIK, and `type` only supports 'company'. This reduces ambiguity 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 time-windowed change feed for companies, with concrete natural-language examples ('What's new with X', 'updates on Acme'). It explicitly contrasts with entity_profile, making the tool's scope distinct and differentiating it from sibling tools.

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

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

It gives direct usage context via query examples and states when to use an alternative: 'Use entity_profile instead when you want the static profile'. It also describes source fallback behavior (GDELT→GNews) and soft-fail conditions, providing decision-relevant 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 specify idempotentHint=true and destructiveHint=false; the description adds valuable context about persistence duration (24 hours for anonymous sessions, persistent for authenticated users) and scoping by identifier. Does not contradict annotations.

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

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

Three sentences, front-loaded with the core action, examples embedded naturally, and no fluff. Every sentence adds meaningful information, making it appropriately sized for a simple storage 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?

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description covers all essential aspects: what to store, when to use, persistence behavior, and relationship to sibling tools. No gaps remain.

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

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

Schema already describes both parameters fully (100% coverage). The description adds real-world examples for keys and values ('subject_property', 'target_ticker', 'user_preference') and explains the key-value nature, exceeding 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 uses a specific verb ('Save data') plus resource ('key-value pair') and explains the purpose ('reuse later across sessions'). It clearly distinguishes from siblings by naming recall and forget as complementary 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?

Explicitly states when to use ('when you discover something worth carrying forward') with concrete examples (ticker, address, preference, research subject). It also clarifies behavior for authenticated vs anonymous sessions, and references companion tools for retrieval and deletion.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description goes beyond annotations by disclosing that each call 'cascades through several lookup endpoints internally,' plus details on data sources (SEC EDGAR, RxNorm) and citation URIs. This is rich behavioral context that helps the agent anticipate latency and output composition.

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

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

The description is well-structured with clear sections (query examples, purpose, usage directive, supported types). Every sentence provides useful information—no filler or repetition. It is front-loaded with the core purpose and usage guidance before detailed type breakdowns.

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

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

Despite having no output schema, the description thoroughly explains return values for both supported types (ticker, CIK, company_name, citation URI; RxCUI, ingredient, brand, citation). It also covers input variations, auto-disambiguation, and internal behavior, making it complete for a two-type resolution tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining allowed input formats per type (ticker, CIK, name; brand/generic name) with concrete examples (ozempic, metformin) and describing what each type returns. This enriches parameter understanding but doesn't introduce fundamentally new meanings.

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: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides specific verbs and resources, includes illustrative query examples, and distinguishes itself from siblings like entity_profile and compare_entities by focusing on name-to-ID mapping.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use trigger. It also explains the tool replaces 2-3 manual lookups, reinforcing its utility. However, it doesn't explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing safety. The description adds meaningful behavioral details beyond this: it internally invokes ai_visibility_check, ranks entities by score, and surfaces most/least recognized. It also discloses the model-specific _apiKey requirement and that 'workers-ai' is the free default, which is not apparent from annotations or schema alone. While it doesn't discuss rate limits or temporal freshness, the annotations plus description are sufficient.

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

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

The description is four dense sentences that cover purpose, mechanism, use case, and return fields. Every sentence contributes unique information—there is no repetition of parameter names or annotation values, and no filler. It is front-loaded with the primary action ('Compare AI visibility across multiple entities side-by-side') and immediately explains the internal process and output.

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

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

There is no output schema, but the description explicitly listing the return components ('ranked list with score, confidence, signal density per entity') compensates for that gap. It also explains the optional model selection and _apiKey behavior, the semantics of the first entity vs. competitors, and the intended audit use case. Given the tool's moderate complexity (4 params, one required, no nested objects), this description leaves little ambiguity.

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

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

Schema description coverage is 100% (all 4 parameters are described in the input schema), so the baseline is 3. The description supplements this with valuable interpretive context: the first entity is treated as the 'subject' for the narrative and the rest as competitors, and the 'context' parameter is given a real-world example ('B2B SaaS', 'Boston restaurant') to clarify disambiguation. 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 uses a specific verb ('Compare AI visibility') and clearly identifies the resource ('multiple entities side-by-side'). It distinguishes itself from the sibling 'ai_visibility_check' by explicitly referencing it as the sub-probe and adding ranking/comparison behavior, making it clear this is for multi-entity competitive audits rather than single checks.

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 concrete use case ('competitive AI-marketing audits') and an illustrative example ('does Claude know about us as well as our competitors?'). However, it does not explicitly state when to avoid this tool or name an alternative (e.g., 'for a single entity, use ai_visibility_check'), so it misses the explicit when-not/alternatives bar for 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?

Discloses important behavioral traits beyond annotations: composite fan-out across two services, partial failure degradation, 5-30s first measurement delay for bundlephobia, sources_failed reporting on timeout, and ecosystem limitation (NPM only in v1). Annotations already state readOnly/idempotent/non-destructive, and the description adds valuable operational context 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?

Though longer than average, every sentence serves a purpose: defining scope, enumerating sources, listing output fields, giving usage triggers, noting ecosystem boundaries, and explaining failure behavior. The structure is logical and front-loaded with the core purpose, making it efficient for AI parsing.

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, two sources, partial failure, latency) and absence of an output schema, the description fully compensates by listing the exact summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, alternative versions, and timeout behavior. Nothing critical is left undefined.

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 'package' and 'version' have descriptions, including scoped package acceptance and default-to-latest behavior. The description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states a composite check for npm packages using deps.dev and bundlephobia, with a specific verb ('scan') and resource ('npm package'). It explicitly positions itself as a one-call answer to 'should I add this package' and distinguishes it from the sibling tool scan_competitor_ai_presence by focusing on dependency safety/size rather than 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?

Provides explicit when-to-use triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives a clear exclusion: non-NPM ecosystems (PyPI, Maven, Cargo, Go) should go directly to deps.dev:version, which is an alternative tool usage.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to disclose safety. It adds the return format (text and IDs) and the matching behavior, which is useful context, but it does not describe search nuances like ranking or filtering.

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 sentence, front-loaded with the verb, and provides essential information without fluff. Every word serves a purpose.

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

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

Given the tool's simplicity (one parameter, output schema available, strong annotations), the description is sufficient for an agent to invoke it correctly. It defines the search input and the expected output shape.

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

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

The single parameter 'query' has 100% schema description coverage, and the description repeats the same semantics ('keyword or phrase', 'within advice text'). The schema already defines it, so the description adds no additional 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's function with a specific verb ('search'), the resource ('advice'), and the output ('matching advice slips with text and IDs'). This distinguishes it from sibling tools like get_advice or random_advice, which have different retrieval patterns.

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

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

The description implies usage when a user needs to find advice by keyword, but it does not explicitly mention when to prefer this over get_advice or random_advice. There is no exclusion or alternative guidance, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent; description adds concrete behaviors: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings + cosine over 500-char overlapping windows, and truncates inputs >200K chars with a flag. 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?

Five sentences, front-loaded with the core action, followed by usage guidance and technical specifics. No filler — every sentence adds 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 search tool with 3 simple params and no output schema, the description covers purpose, when to use, return value shape, algorithm, and input limits. It also pairs with a sibling tool, making it fully actionable.

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

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

Schema covers all three params, but description enriches text (already-pulled record, 200K cap), limit (top-N), and query (natural-language with examples). It also reinforces the role of 'text' as the thing you pass in, beyond the schema's brief descriptions.

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

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

Description opens with 'Semantic search INSIDE a fetched record' — a specific verb (search) and resource (a fetched record). It clearly distinguishes from sibling tools by stating it operates on already-pulled text rather than fetching, and explicitly names ask_pipeworx_grounded as a complement.

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

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

Provides explicit when-to-use: 'Use when the record is too big to cram into the prompt.' It also gives a pairing with ask_pipeworx_grounded ('fetch with the gateway, ground over the relevant passages') and explains the benefit (saves context, verifiable offsets).

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. It discloses authentication requirements, per-type parameters with examples, delivery channel constraints (e.g., phone must be verified, 10/day cap), webhook signing secret returned only once, HMAC verification details, and auto-disabling after 10 consecutive failures. This is rich, actionable 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 long but dense with necessary information. It is front-loaded with the core purpose and then logically structured by type and delivery channel. Every sentence serves a purpose, though it could arguably be broken into bullet points for even easier scanning.

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 (3 nested object parameters, multiple types, delivery options) and no output schema, the description is complete. It states the return value (subscription id), covers all subscription types, explains delivery behavior, and includes prerequisite context. No critical gaps remain.

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

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

Even though the schema has 100% coverage, the description adds substantial meaning. It explains each subscription type with concrete parameter examples (e.g., 'sec_8k: items:["5.02"]'), details delivery channel formats (email, sms, webhook), and clarifies the webhook signing secret behavior. This goes beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes it from sibling tools like list_subscriptions, recent_alerts, and unsubscribe. The supported types and delivery channels are also explicitly enumerated.

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 conveys when to use the tool: to set up persistent monitoring for specific event streams. It includes prerequisites ('Requires a Pipeworx OAuth account') and excludes anonymous/BYO usage. While it does not explicitly name alternatives, the context makes the intended use clear relative to siblings like unsubscribe and list_subscriptions.

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

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

Annotations already declare read-only/idempotent; the description adds behavioral details about returning category-bucketed questions with tool+argument shapes drawn from a live catalog. It doesn't mention side effects or auth, but the read-only annotation covers the safety profile.

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 bit long but efficiently packs example user queries, purpose, return value, and usage into a structured paragraph. Each sentence adds value, and the front-loaded examples help orient the agent.

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

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

Without an output schema, the description thoroughly explains return values, lists the categories, covers the parameter, and gives usage context. Annotations handle safety, making this a complete package for an onboarding 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 schema fully documents `topic` with allowed values and the omit behavior. The description adds example values ('finance', 'pharma', 'betting') but doesn't substantially exceed the schema's coverage, so a baseline 3 is appropriate.

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

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

The description clearly states the tool suggests example questions for what Pipeworx can do, and explicitly positions it as the onboarding entry point. It distinguishes from siblings by saying 'Use this FIRST' and mentions meta-tools, so the purpose is unambiguous.

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

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

Provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with or without a topic. It doesn't explicitly exclude alternatives like discover_tools, but the directive is clear enough for most cases.

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

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

The description adds significant behavioral context beyond annotations: it reveals a soft-delete mechanism ('The row is deactivated (not deleted)') and explains how historical events remain available. This is more informative than simply relying on annotations like idempotentHint and destructiveHint. 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 exactly two sentences: first states the core action, second adds important behavioral nuance. Every word earns its place, no fluff. It is front-loaded with the primary action.

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

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

For a simple single-parameter tool with strong annotations and no output schema, the description is complete. It covers what the tool does, ownership restrictions, the persistence behavior (deactivate not delete), and the impact on historical data. No missing context needed for selection or invocation.

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

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

The input schema already provides full coverage for the single parameter 'id' with description 'Subscription id (uuid) returned by subscribe.' The tool description only mentions 'by id', which adds no new meaning. Baseline 3 is appropriate given 100% 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 action: 'Cancel a subscription by id.' The verb 'Cancel' and resource 'subscription' are specific, and the title 'Unsubscribe from Alerts' reinforces the purpose. It is distinct from sibling tools like list_subscriptions and subscribe.

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: 'Ownership is enforced — you can only cancel your own subscriptions' indicates when the tool is applicable and constraints. It implies usage for unsubscribing while preserving historical data via 'recent_alerts'. However, it does not explicitly name alternatives or exclusions, though sibling tools make the use case obvious.

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 a safe read-only, idempotent operation. The description adds valuable behavioral context: the fast path for company-financial claims with exact percent-delta math, fallback to grounded pipeline with verbatim evidence, and the list of possible verdicts. This goes beyond the annotations without contradicting them.

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

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

Though detailed, the description is tightly structured and every sentence serves a purpose: trigger phrases, routing logic, output summary, and efficiency benefit. It is front-loaded with examples and avoids redundancy, making it appropriately sized for the tool's complexity.

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

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

The description fully covers inputs (claim and tolerance), behavior (two routing paths), outputs (verdict, citation, reasoning), and even explains why it replaces multiple sequential calls. Given no output schema exists, the description sufficiently communicates what the agent can expect, and the two-parameter schema is fully addressed.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description enhances this by explaining how tolerance_pct overrides the claim wording's implied tolerance and providing concrete guidance (e.g., set 1-2 for hallucination detection). The claim parameter also gets realistic examples. This adds meaningful 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: natural-language claim verification against authoritative sources. It provides specific trigger phrases and examples, and distinguishes itself by covering both structured financial claims and general factual claims, making it distinct from sibling tools like ask_pipeworx_grounded.

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

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

It explicitly says to use whenever the agent needs to check factual correctness, and describes the two routing paths (SEC EDGAR for company-financial, grounded pipeline for everything else). It lacks explicit when-not-to-use guidance or named alternatives, but the usage context is clear and practical.

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