Wiktionary

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

Beyond annotations (read-only, idempotent), description discloses that apiKey is passed to Anthropic, cost implications, and return structure (per-model scores, raw_response). Adds meaningful 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?

Three well-structured sentences with front-loaded purpose, concise but complete. No unnecessary words.

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

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

Covers all key aspects: input, models, optional key, return format. No output schema, but description explains output structure. Slight gap: no error handling details, but acceptable for a probing 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%, but description adds context beyond schema descriptions: explains entity is the query target, models default behavior, _apiKey passthrough, and context disambiguation. Adds value beyond schema.

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

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

Description clearly states the tool probes LLMs for visibility scoring, specifies default model and optional anthropic, and lists use cases. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on per-model visibility metrics.

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 use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use which model. Lacks explicit when-not scenarios but context is clear.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses that the tool routes to many underlying tools, fills arguments, and returns citations, which is valuable behavioral context. It also notes 'one fast call' and 'works on every tier', adding practical 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?

Although long, every sentence serves a purpose: first the direct preference directive, then the domain list, then trigger phrases and examples, then default status and escalation paths. It is front-loaded with 'PREFER OVER WEB SEARCH' and uses clear structure via bolded phrases and examples.

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

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

Given no output schema, the description adequately explains the return format ('structured answer with stable pipeworx:// citation URIs') and covers a wide range of potential inputs. It also mentions alternatives, making it complete enough for an agent to choose and invoke the tool correctly.

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

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

With 100% schema coverage and detailed alias descriptions, the baseline is 3. The description adds meaning by enumerating a broad range of question domains (SEC filings, FDA, FRED/BLS, patents, real estate, etc.) and giving example questions, which helps the agent select appropriate query phrasing.

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: routes a natural-language question to one of 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with citation URIs. It explicitly distinguishes itself from siblings ask_pipeworx_grounded and deep_research, making the tool's specific role unambiguous.

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

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

The description provides explicit when-to-use guidance with 'PREFER OVER WEB SEARCH', trigger phrases like 'what is' and 'look up', and multiple concrete examples. It also states when to step up to alternatives, naming ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part questions, plus a note on breaking-news.

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

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

Description adds valuable behavioral context beyond annotations: it is a live experimental edge, with candidate routing improvements enabled during tests, results compared against the stable router for potential merges, and it 'falls back to nothing' meaning it is a fully working router. Annotations already cover readOnly/idempotent/open safety, so the added dynamic experimental behavior is good extra 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?

A four-sentence paragraph that front-loads the beta relationship, then explains current state, usage instruction, and experimental nature. Every sentence earns its place with no wasted words; the specific retire date adds credible context for current equivalence.

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 adequately covers what the tool is, how to use it, and its experimental nature. It relies on knowledge of ask_pipeworx for response shape and argument specifics, so it is not fully self-contained, but in a sibling-tool context it is sufficiently complete.

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

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

Input schema covers all 6 parameters (question plus aliases) with 100% description coverage. The description only mentions 'same arguments' as ask_pipeworx and adds no additional semantic detail beyond what the schema provides, so the baseline of 3 for high coverage applies.

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

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

Description identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. The intended action is implied through 'Use it exactly like ask_pipeworx' and the title, but there is no explicit verb like 'ask' or 'route', making it clear yet somewhat reliant on sibling context.

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 it exactly like ask_pipeworx when you want the newest routing.' It also clarifies current equivalence with the stable router when no candidate is active, giving a clear condition for when to prefer this beta variant over the stable ask_pipeworx.

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

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

Beyond the readOnly/openWorld annotations, the description details the exact return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and enumerates all refusal reasons. It also discloses the extra LLM call cost and the strict grounding behavior ('using ONLY what the tool result contains'). No contradiction with annotations.

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

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

The description is dense but every sentence adds value: the opening line states the core value, the middle explains the mechanism and output format, and the ending gives usage guidance and cost trade-off. It is front-loaded with the most important information and stays focused without wordy repetitions.

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 detailing the success and refusal response structures. It also covers the routing behavior, the one-extra-call cost, and appropriate use cases, making it complete for an agent to decide 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?

The input schema already provides 100% coverage, describing the 'question' parameter and five aliases (q, text, input, query, prompt). The description adds no parameter-specific meaning beyond saying the tool 'fills arguments' during routing, which is sufficient given the schema's completeness. Baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly identifies this as a 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism ('EXTRACTS the answer using ONLY what the tool result contains'). It explicitly contrasts with sibling tool ask_pipeworx by noting 'Same routing' but different extraction approach, making the tool's unique 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 provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives a clear exclusion: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups,' naming the alternative and the trade-off.

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 aligns with annotations (readOnly, idempotent, non-destructive) and adds extensive detail: classification, fan-out logic, response shapes, resolver contracts, safety mechanisms (low-confidence, closed markets, wide spreads), and cancellation rules. This far exceeds what annotations provide.

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

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

The description is very long and dense, packed with information but lacking clear structure (e.g., bullet points or sections). While every sentence adds value, the length might overwhelm an agent. It could be more concise and better organized for quick consumption.

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 params, no output schema, rich annotations), the description covers all necessary aspects: input formats, output shapes, edge cases, safety mechanisms, and practical guidance. An agent can confidently invoke this tool based solely on the description.

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

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

Schema coverage is 100% (all three parameters have descriptions in the schema). The description adds context for `market` (multiple input formats), `depth` (quick vs thorough with default), and `include_raw` (practical guidance on when to use). The examples for `market` also enhance clarity.

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 verb 'Research' and the resource 'Polymarket bet', and distinguishes it from sibling tools by detailing its comprehensive, all-in-one nature. It lists multiple input formats (slug, URL, question text) and provides concrete use cases ('should I bet on X').

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 examples of when to use the tool ('should I bet on X', 'what does the data say about Y') and mentions it frees the agent from manually fanning out to other tools. However, it does not explicitly state when NOT to use it or name alternative tools for specific subtasks (e.g., using `polymarket_arbitrage` for arbitrage).

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, so safety is clear. The description adds behavioral details: for companies, it pulls latest 10-K revenue/net income/cash/debt with off-calendar handling; for drugs, FAERS counts; results are sorted by primary metric; returns citation URIs. This provides useful context beyond annotations.

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

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

The description is a single paragraph that efficiently packs multiple trigger phrases, use-case guidance, data source details, and output format. It's front-loaded with trigger phrases. Could be slightly more structured but is not overly verbose.

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

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

Given only 2 parameters and no output schema, the description comprehensively covers what the tool does, what data it retrieves, how results are sorted, and the type of citations returned. No critical gaps are evident.

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

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

Schema coverage is 100%, and schema already provides enum descriptions and constraints. The description adds context for the 'values' parameter: clarifies that for companies it expects tickers/CIKs and for drugs it expects drug names, and implicitly explains the effect of 'type'. This adds value beyond the schema's brief descriptions.

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

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

The description uses specific verbs like 'compare' and 'side-by-side comparison' and clearly identifies the resource (companies or drugs). It distinguishes from sibling tools by noting it replaces up to 15 sequential lookups, making its purpose unambiguous.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases like 'compare X and Y', 'X vs Y', 'which is bigger', etc. This gives clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses account requirements, paid-tier limitations, parallel facet routing, gaps[], contradictions[], latency expectations, and the guarantee that citations are always fetchable. This is rich behavioral context without contradicting any annotation.

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

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

The description is a single dense paragraph but every sentence contributes substantive information (account, alternatives, data sources, output format, use cases, latency). It could be improved with bullet points for easier scanning, but is not unnecessarily verbose given the tool's complexity.

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

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

With no output schema, the description thoroughly explains the findings packet structure (evidence, confidence, source, fetched_at, citation_uri, gaps, contradictions) and covers account requirements, alternatives, edge cases, and expected latency. This is complete and actionable for an agent.

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

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

The input schema already fully documents the question and depth parameters (including enum details and behavior). The description adds only minor external constraints (e.g., 'depth:"thorough" needs a paid plan') and timing estimates, so its incremental value over the schema is limited.

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 core function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly differentiates from open-web search. It also names and contrasts with sibling ask_pipeworx, making the purpose and scope unmistakable.

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

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

It provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also offers a fallback if not signed in, covering all main scenarios.

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

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

Annotations already cover read-only, idempotent, open-world behavior; description adds useful context about grouping by POS, which goes beyond annotations.

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

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

Single sentence with no wasted words, front-loaded with 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?

For a simple lookup tool with output schema, the description is mostly adequate but the missing parameter documentation for 'word' is a clear gap.

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

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

Schema coverage is only 50% (word parameter lacks description) and the description does not explain any parameters or add meaning beyond what the schema 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?

Description clearly states the tool returns parsed definitions grouped by part-of-speech sections, distinguishing it from sibling tools like etymology or pronunciations.

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

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

Description provides no guidance on when to use this tool versus alternatives, nor any context or exclusions.

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

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

Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true; description adds that returns top-N tools with full schemas and curated examples, ready to call directly. No contradictions, and adds valuable context 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?

Front-loaded with purpose and examples, but slightly verbose. Remains highly informative.

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

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

No output schema but description explains return format (names, descriptions, schemas). Covers usage, purpose, and output, making it complete for a discovery 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%, description adds natural language examples and lists multiple aliases for query, enhancing meaning beyond schema descriptions.

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

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

The description clearly states the tool is for finding tools by describing data or task, listing diverse domains like SEC filings, FDA drugs, etc. It distinguishes itself from siblings by focusing on tool discovery rather than data retrieval.

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

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

Explicitly advises to call this first when many tools are available, with examples like 'analyze housing market trends'. Lacks explicit when-not guidance but provides clear 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?

Discloses that it fans out across multiple sources, returns specific fields like recent_filings with URIs, notes USPTO source sunsetting (soft-fails), and explains behavior. No contradiction with annotations (readOnlyHint, etc.).

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

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

Description is dense but well-organized. Starts with example queries, then explains behavior and details. Slightly lengthy but all sentences add 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?

Thoroughly covers complexity: multiple sources, fallback behavior, patent sunsetting, return structure. No output schema but description sufficiently outlines return values. Complete for a profile 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%; description adds extra context: value must be ticker or zero-padded CIK, names not supported, provides examples. Adds meaning beyond schema.

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

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

Description clearly states verb+resource: 'full cross-source profile of a US public company.' Lists data sources and specific outputs, and distinguishes from sibling tools like 'resolve_entity' and chaining single-pack lookups.

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

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

Explicitly tells when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states when not to use: 'names not supported (use resolve_entity first if you only have a name).' Includes example queries.

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

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

Annotations provide read-only, idempotent, and non-destructive hints, so the safety profile is clear. The description adds that the etymology comes from wikitext, providing minimal extra context. No contradictions.

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

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

The single-sentence description is extremely concise with no wasted words. However, it could be slightly more informative without losing conciseness.

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

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

Given rich annotations and an output schema, the description is insufficient. It does not specify output format, source of wikitext, or language scope, leaving significant 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?

With 0% schema description coverage, the description fails to explain the meaning or usage of the 'lang' and 'word' parameters beyond their names and types.

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 'Etymology section extracted from wikitext' clearly states the action (extracting) and the resource (etymology section from wikitext). This differentiates it from sibling tools like 'definition' and 'pronunciations'.

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?

No usage context, prerequisites, or alternative tools are mentioned. The description does not help an agent decide when to use this tool versus others.

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

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

Annotations indicate destructive hint; description confirms deletion and adds context about clearing sensitive data, but does not go beyond annotations significantly.

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

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

Three concise sentences: purpose, usage conditions, related tools. No unnecessary words.

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

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

Simple tool with one required parameter; description covers purpose, usage, and related tools adequately.

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

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

Parameter 'key' is fully documented in schema with 100% coverage; description adds no extra meaning, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key.' with a specific verb and resource, distinguishing it from siblings like 'remember' and 'recall'.

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 conditions ('context is stale, the task is done, or you want to clear sensitive data') and mentions companion tools ('Pair with remember and recall').

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, etc. The description adds behavioral context: it fetches the page, extracts title/description/key links, and outputs markdown. It also explains the output's purpose (ready to drop at site-root/llms.txt), which is beyond the annotations.

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

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

The description is three concise sentences: first sentence states the purpose, second explains the process, third lists use cases. No fluff or redundancy. Every sentence adds value.

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

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

Given the tool has only 2 parameters, no output schema, and comprehensive annotations, the description covers all necessary context: input (URL), process (fetch/extract/emit), output (markdown text), and real-world applications. It leaves no gaps for an AI agent.

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

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

Schema description coverage is 100%, so the parameters (url, max_links) are fully documented in the schema. The description does not add extra semantics or clarify constraints beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and the scope 'for any URL'. It distinguishes from sibling tools by specifying the exact output format and use case, leaving no ambiguity about 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 use cases (index client site, draft llms.txt, audit competitor) but does not mention when not to use it or list alternatives. It gives clear context for appropriate usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds value by listing returned fields and clarifying default behavior (active subscriptions only). No contradictions.

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

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

Two concise sentences, front-loaded with purpose and output, then usage guidance. No waste.

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

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

Covers purpose, output fields, and usage. May lack error handling or pagination info, but for a simple list tool it is complete enough.

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 a clear description for the only parameter. The description does not add much beyond the schema, but the default behavior is implied. Baseline 3 is appropriate.

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

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

Clearly states the verb 'list', resource 'subscriptions', and scope 'the caller's active subscriptions'. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly tells when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. No mention of when not to use, but sufficient for this 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?

Goes beyond annotations by describing the claim_token workflow (filing without account returns a token that can later be passed to read status), rate limit (5 per identifier per day), and guarantee that it's free and doesn't count against tool-call quota. No contradiction with annotations (readOnlyHint=false aligns with the write operation).

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?

Despite being multi-sentence, every sentence contributes necessary guidance—scope, use-cases, caveats, and token workflow. It's front-loaded with the action and then elaborates logically.

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

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

Covers the full behavior of the tool including rate limits, token retrieval, and filter that only Pipeworx-served tools should be reported. With no output schema, the description correctly explains the claim_token response mechanism.

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 documents 100% of params, but description adds important usage context: describe issues in terms of Pipeworx tools/packs, don't paste end-user prompt, and explains the claim_token use-case (`pipeworx_feedback({claim_token:"pwfb_…"})`) to retrieve status. This enriches the bare schema definitions.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the tool as a feedback mechanism. It distinguishes itself from sibling Q&A tools by focusing on reporting issues with tools served by this Pipeworx connection.

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 specifies when to use: bug, feature/data_gap, or praise, and gives 'when not to use' by excluding tools from other MCP servers, directing the user to file there instead. Even clarifies how to identify which tools qualify.

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

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

Annotations indicate read-only, non-destructive, idempotent. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior, and self-aggregating nature. 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?

Two paragraphs: first sentence states purpose, three bullet use cases, final sentence adds source and caching. No filler, front-loaded with key information, well under 100 words.

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

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

For a simple tool with one optional parameter and no output schema, the description explains return values (top tools, packs, volume) and caching. 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 fully describes the 'window' parameter with enum and behavioral guidance. The tool description only mentions window options without additional meaning. Baseline schema coverage 100% yields 3.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, with three concrete use cases. It effectively differentiates from sibling query tools by focusing on aggregated trending.

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 specific use cases (discovering hot data, confirming canonical choice, checking alignment) but does not explicitly state when not to use or mention alternatives. Still offers strong guidance for correct selection.

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

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

Description goes far beyond annotations, detailing the scanning logic (monotonicity violations, partition_check), semantic anchor (Jaccard similarity), partition filter (placeholder slug handling), and fill check (realizable vs theoretical edge). Behavioral traits like read-only idempotent checks are consistent with annotations, no contradictions.

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

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

Description is comprehensive but slightly verbose; however, every sentence adds value. Structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). A minor reduction could improve conciseness without losing clarity.

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

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

Given the tool's complexity (two modes, lack of output schema, multiple internal checks), the description covers all essential aspects: response structure, fill risk, filters, and mode-specific behavior. No gaps in context for an AI agent to use it correctly.

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

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

Even though schema coverage is 100%, the description adds rich meaning: for 'event', explains it walks child markets and performs date-axis/threshold-axis checks; for 'topic', explains cross-event scanning with similarity threshold. It also notes that full Polymarket URLs are accepted for event, which schema does not specify.

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

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

Description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies the resource and distinct operation: 'Find arbitrage opportunities on Polymarket'. The two modes (event and topic) are clearly differentiated, and the tool stands out from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly states when to use each parameter: call with NO args for trending scan, 'event' for a specific market, 'topic' for cross-event scanning. Provides practical usage tips, e.g., 'event (recommended for a specific market)', and explains when cross-event mode catches patterns single-event misses. Also includes warnings about fill check and partition filter.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds extensive behavior: caching (1h KV), edge computation details (after slippage), Kelly sizing, diagnostic fields, and filtering logic. No contradictions.

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

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

The description is dense and well-structured, starting with purpose then detailing segments, knobs, and response. Every sentence adds value, though slightly lengthy. Minor conciseness improvement possible.

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

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

Given 9 parameters, no output schema, and domain complexity, the description is exceptionally complete: covers computation, response format, diagnostics, caching, and caveats like Fed data unreliability.

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%. The description adds rationale and interactions beyond schema, e.g., why min_kelly does not filter partition arbs, and defaults like slippage_pp with explanation of Polymarket fees.

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

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

The description states a specific verb ('scan', 'return') and resource ('Polymarket markets'), clearly indicating the tool finds opportunities where model data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage by detailing model families and segments.

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: 'Built for what should I bet on today' and guidance on when to use knobs (e.g., min_liquidity to drop thin books). However, it does not explicitly exclude scenarios or compare with alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds rich behavioral context beyond these: details on snapshot gaps (cache miss), response fields (tracked, expired, snapshot_dates), computation of decay_pp_per_day, and that decay numbers come from daily closes not intraday. No contradictions.

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

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

The description is well-structured with a clear core question, parameter definitions, response breakdown, and LIMITS section. It is concise for the amount of detail provided, though it could be slightly tighter by removing parenthetical asides or redundant phrasing. Overall, every sentence 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 no output schema, the description explains the entire response structure with fields like tracked (with subfields first_seen, trend, decay_pp_per_day), expired (with lifespan_days), and snapshot_dates. It also covers limitations (TTL, snapshot start). For a tool with only two optional parameters, this is exceptionally complete.

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

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

Input schema already documents both parameters (days, window) with descriptions, defaults, and ranges. The description restates these values (default 14, max 30; default '1wk') but does not add significant new semantics beyond what the schema provides. With 100% schema coverage, the baseline is 3.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?', and distinguishes itself from sibling tools like polymarket_edges by focusing on historical time-series rather than just current edges.

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

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

The description provides a rationale for when to use: comparing a fresh wide edge versus an old wide edge ('the latter is wide for a reason nobody is willing to take'). It also includes LIMITS detailing constraints like the 60-day snapshot TTL and dependency on snapshotting being enabled. However, it does not explicitly exclude alternative tools or provide comprehensive when-not-to-use 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 (readOnlyHint, idempotentHint, destructiveHint=false) already declare the tool's safe, read-only nature. The description adds valuable context about behavior, such as walking the ladder and returning a verdict, beyond what annotations provide.

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

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

The description is lengthy but well-organized with clear sections for single-market and basket modes. It is front-loaded with the core purpose and requirements. While every sentence adds value, slight conciseness improvements are possible.

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

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

Despite lacking an output schema, the description thoroughly explains return fields and risks (e.g., partial basket fills leading to directional risk). For a complex tool with nuanced behavior, it is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning by detailing how size_usd is interpreted differently for buys vs sells and single vs basket, and explains the default side logic for basket mode.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with specific details, leaving no ambiguity.

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

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

The description explicitly instructs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the reasoning, effectively differentiating from 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral context: compatibility_warning conditions, temporal alignment, skipped cross types, and real-world frequency of tradeable spreads. No contradiction.

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

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

Description is dense but well-structured with sections for modes, response, safety fields. Slightly long but each sentence provides value. Could be more concise, but front-loaded with key info.

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

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

No output schema, but description thoroughly explains response fields (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). Covers all necessary behavioral details for a complex tool.

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

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

Schema has 100% description coverage, so baseline is 3. Description adds value by explaining the topic macro shortcuts, providing examples, and clarifying behavior when using explicit tickers vs topics.

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 explicitly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, using specific verb 'cross-venue spread' and resources 'Kalshi' and 'Polymarket'. It differentiates from sibling tools like 'polymarket_arbitrage' by being a paired comparison tool.

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?

Clearly describes two modes (topic and explicit tickers) and when to use each. Provides warnings that pre-mapped topics often return compatibility warnings. Could improve by explicitly contrasting with sibling 'polymarket_arbitrage' but still strong.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds only 'extracted from wikitext', which is a minor source detail but does not disclose important behavioral traits like what happens for missing words, supported languages, or format of transcriptions.

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 very short (one sentence), which is concise but lacks structure. It fits in one line, but sacrifices necessary details. The brevity is acceptable for a simple tool, but the lack of parameter or usage context is problematic.

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 an output schema exists, return values are not required. However, the description does not cover the tool's behavior for edge cases (e.g., unsupported languages, multiple pronunciations) or clarify that 'wikitext' refers to a specific source. It is minimally complete for a tool with two parameters and no parameter descriptions.

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 0%, yet the description provides zero information about the two parameters (lang and word). The examples in the schema are not part of the description, so the agent gets no semantic guidance beyond what the schema's property names imply.

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 extracts IPA/phonetic transcriptions from wikitext, which is a specific verb+resource. Among sibling tools like 'definition' and 'etymology', this tool's purpose is distinct and immediately clear.

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

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

No guidance on when to use this tool versus alternatives. It does not mention any prerequisites, typical use cases, or situations where this tool would be preferred over other pronunciation-related tools (none exist in siblings, but still lacking context).

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false. The description adds context beyond annotations: scoping to identifier, listing behavior without key, and pairing with forget/remember. No contradictions.

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

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

Two sentences with no wasted words. Front-loaded with the main purpose, then adds context. Every sentence earns its place.

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

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

For a simple single-parameter retrieval tool with no output schema, the description covers all needed context: retrieval vs list, scoping, sibling tools. No gaps.

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

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

Schema coverage is 100% with description in the schema for 'key'. The description reiterates the behavior but does not add new details beyond what the schema 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 it retrieves a value saved via remember or lists all keys if omitted. It uses specific verbs ('retrieve', 'list') and distinguishes from siblings remember and forget.

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

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

It explains when to use (look up stored context) and mentions sibling pairings (remember, forget) and scoping. Although it doesn't explicitly state when not to use, the guidance is clear and comprehensive.

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 describes the mark_read parameter as setting events read, which modifies state, contradicting the readOnlyHint=true annotation. This is a serious inconsistency, leading to a low score.

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

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

The description is concise, with every sentence adding value. It is front-loaded with the core purpose and uses clear language.

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 return structure, parameters, and alternative access, making it largely complete. However, the annotation contradiction undermines trust, slightly reducing the score.

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

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

All parameters have schema descriptions, and the description adds value with examples (e.g., 'sec_8k', ISO timestamp) and default behavior (mark_read default false). This slightly enhances understanding beyond the schema.

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

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

The description clearly states it pulls fired events from a subscription feed, specifying the resource and verb. It does not explicitly distinguish from siblings like 'list_subscriptions', but 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?

The description provides filtering options and mentions polling suitability, as well as an alternative HTTP endpoint. However, it lacks explicit when-not-to-use guidance or comparison to 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: parallel fan-out to multiple sources, fallback logic for GDELT→GNews, and soft-fail for USPTO due to PatentsView API sunset. No contradictions.

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

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

The description is dense but well-structured: it opens with example queries, explains the tool's behavior with specific sources, and ends with the alternative tool. Every sentence adds unique value, though it could be slightly more concise.

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

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

No output schema is provided, but the description explicitly states the return structure ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). This sufficiently documents what the tool returns.

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

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

Schema has 100% description coverage for all 3 parameters. The description adds value by clarifying that 'since' accepts ISO dates or relative shorthand (e.g., '7d', '3m'), recommends '30d' or '1m' for typical monitoring, and notes that 'value' can be a ticker or zero-padded CIK.

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 specifies the tool as a change feed combining SEC EDGAR, GDELT/GNews, and USPTO data, with clear query patterns ('What's new with X') and distinguishes it from the sibling tool 'entity_profile' which provides static profiles.

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

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

Explicitly states when to use this tool (for recent changes) and when to use the alternative ('Use entity_profile instead when you want the static profile'). Also explains fallback behavior between GDELT and GNews.

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

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

Annotations already provide idempotentHint=true, indicating repeated calls have the same effect. The description adds valuable behavioral context such as persistence duration (24 hours for anonymous, persistent for authenticated) and scoping by identifier, which goes beyond annotations.

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

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

Three tightly packed sentences with no wasted words. The first sentence states the core purpose, the second provides usage guidance, and the third adds behavioral details. Perfectly front-loaded and structured.

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

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

For a simple tool with only two required parameters and no output schema or nested objects, the description covers all essential aspects: purpose, usage, pairing, scoping, and retention. 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 coverage is 100% with descriptions for both parameters. The description adds usage examples for the key ('subject_property', 'target_ticker') and clarifies that value is any text, enhancing the meaning beyond the schema.

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

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

The description clearly states the tool saves data for later reuse, using specific verbs like 'save' and 'store', and distinguishes itself from the related tools 'recall' and 'forget' that are listed as 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 explicitly states when to use ('when you discover something worth carrying forward'), provides context on scoping and retention (authenticated vs anonymous), and mentions the complementary tools 'recall' and 'forget'.

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

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

Beyond the readOnly and idempotent annotations, the description discloses key behaviors: all returned identifiers are source-labelled, unresolved identifiers appear under 'unresolved' rather than being omitted, and LEI/FIGI enrichment degrades gracefully if upstream services fail. This is valuable context not captured by annotations.

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

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

The description is long but every sentence contributes: example queries, use-case instruction, supported types, source attribution, degradation behavior, and efficiency payoff. It is well-organized with clear sections (SUPPORTED TYPES, degradation note) and no repetitive 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?

Given no output schema, the description compensates by explaining what identifiers are returned (CIK, ticker, LEI, FIGI, RxCUI), how they are labelled (source), how unresolved data is reported, and degradation behavior. It is thorough enough for an agent to understand the tool's full behavior and output expectations.

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 already provides 100% coverage, describing both 'type' enum and 'value' with examples for company and drug. The description adds extra context about source systems (SEC, GLEIF, OpenFIGI) and input format flexibility, but it mostly reinforces schema details rather than introducing new parameter meaning, so baseline 3 applies.

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

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

The description explicitly states the tool resolves user-spoken names to canonical/official identifiers, listing concrete query examples (ticker, CIK, LEI, RxCUI). It distinguishes itself as the primary lookup tool for name-to-ID conversion, clearly separating it from sibling tools like entity_profile or search.

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 explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when each supported type applies (company vs. drug) and notes the tool eliminates 2-3 manual lookups, making the context for use highly 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?

The description adds significant behavioral context beyond the rich annotations: it explains that the tool probes each entity with ai_visibility_check, ranks by score, and surfaces the most/least recognized. It also discloses the return format (score, confidence, signal density per entity). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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

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

The description is extremely concise: two sentences that cover purpose, process, and output. Every sentence is meaningful and front-loaded with the core action. No extraneous 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?

Given the multi-entity comparison complexity and the lack of an output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It also clarifies the special treatment of the first entity. The annotations already cover safety and idempotency, so the description completes the picture.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal value: it clarifies that the first entity in the array is treated as the 'subject' for narrative purposes, which is a helpful nuance beyond the schema. No other parameter details are added.

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

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

The description clearly states the verb (compare, probe, rank, surface) and resource (AI visibility of multiple entities). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the competitive benchmarking context.

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

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

The description explicitly states the use case: 'competitive AI-marketing audits' with an example question. It implies that for a single entity, one should use ai_visibility_check instead. However, it does not explicitly list when not to use this tool or mention all alternatives.

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

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

Adds significant behavioral context beyond annotations: fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and a `sources_failed` list is returned. No contradiction with annotations.

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

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

The description is a single dense paragraph but packs all necessary information without fluff. It is front-loaded with the core purpose. While efficient, could benefit from bullet points for 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, no output schema, and multiple sources, the description comprehensively covers inputs, behavioral details, output structure (summary block, per-advisory detail, links, alternative versions), and limitations (NPM only, timing caveats).

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds extra value by giving an example of scoped packages (@types/node) and clarifying that version defaults to latest, which aids agent understanding.

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

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

The description clearly specifies that the tool performs a composite check for npm packages, combining data from deps.dev and bundlephobia. It uses specific verbs like 'scan' and 'fans out', and distinguishes itself from sibling tools by focusing on the npm ecosystem and providing a combined view.

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 an agent asks about safety, popularity, size, or cost of adding an npm package. Also provides exclusion guidance: other ecosystems like PyPI, Maven, Cargo, Go fall under a different tool (deps.dev:version directly).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context that the search is over Wiktionary titles and fulltext, which is useful but does not disclose additional behavioral traits (e.g., pagination, rate limits). It adds some value beyond annotations.

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

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

The description is a single sentence with no wasted words. It is front-loaded and conveys the core functionality efficiently. However, it could be slightly more verbose to improve completeness.

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 has 3 parameters and an output schema, the description is too minimal. It does not explain the nature of results, any required prerequisites, or how to interpret inputs. The agent may struggle to use the tool correctly without additional context.

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

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

Schema description coverage is only 33% (only 'limit' described). The description does not clarify the meaning of 'query' or 'lang' beyond what the schema provides. With low coverage, the description fails to compensate, leaving parameter semantics unclear.

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 tool description clearly specifies the verb (search), resource (Wiktionary), and scope (title + fulltext). This differentiates it from sibling tools like 'definition', 'etymology', or 'pronunciations', which target specific aspects of Wiktionary content.

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

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

The description provides no guidance on when to use this tool versus alternatives. With many sibling tools (e.g., 'deep_research', 'bet_research'), the agent receives no context for selection. No exclusions or usage scenarios are mentioned.

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

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

Annotations declare readOnly, idempotent, and not destructive. The description adds technical details: BGE embeddings, cosine similarity, 500-char overlapping windows, and a 200K char truncation cap with a flag. This goes well beyond the structured data.

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

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

Three well-structured sentences: first targets purpose, second covers when-to-use, third explains technical behavior and limits. 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 no output schema, the description explains return format (passages with offsets and similarity scores), usage context, pairing suggestion, and technical limits. This is 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 covers all three parameters with descriptions (100% coverage). The description provides example queries and notes the default limit, but does not add significant new meaning 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 'Semantic search INSIDE a fetched record' using a natural-language query, distinguishing it from broader search tools. It pairs with ask_pipeworx_grounded, reinforcing a specific use case.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. Provides clear context for when to use this tool vs alternatives.

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

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

Description adds substantial behavioral context beyond annotations: subscription creation returns an ID, requires authentication, details each subscription type's parameters and constraints, and covers delivery mechanisms including webhook signing and auto-disablement. However, the idempotentHint annotation contradicts the description's implication that each call creates a new subscription.

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

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

Single paragraph is efficient and front-loaded with purpose and return value, but could benefit from clearer structure (e.g., bullet points for types). No truly redundant sentences.

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, description explains the return value (subscription ID) and how to retrieve alerts (via feed or delivery). Covers all key aspects: auth, types, delivery, limitations, and operational details like webhook signatures and auto-disablement.

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

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

Schema coverage is 100%, but description enriches each parameter with examples, constraints (e.g., phone must be verified, SMS cap), and type-specific formats. The nested delivery object is fully explained beyond the schema description.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It precisely identifies the action and result, differentiating from sibling tools like unsubscrige and list_subscriptions.

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

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

Explicitly states prerequisites (Pipeworx OAuth account), supported types with detailed parameter examples, and delivery channel constraints (phone verification, 10/day cap). Provides clear context for when and how to use the 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat safety traits. It adds value by detailing the return structure (category-bucketed questions with tool+argument shapes) and mentioning the live catalog of thousands of tools, resulting in 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 well-structured, starting with example queries, then explaining output, and ending with usage guidance. While somewhat long, every sentence adds value and there is no 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 no output schema, the description adequately explains the return value (category-bucketed example questions with tool+argument shapes). It also covers the optional topic parameter and when to use the tool, making it sufficiently complete 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 parameter `topic` is documented in the schema, but the description adds meaning by listing example values (finance, pharma, betting) and clarifying that omission gives a cross-category spread. This enhances understanding beyond schema alone.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It specifies the verb 'returns', the resource 'example questions', and distinguishes from siblings by advising to use this first when unsure what Pipeworx can do.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This provides clear context for when to use it, though it doesn't explicitly mention when not to use it.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) already inform the agent of safe, idempotent behavior. The description adds that it fetches from the Wiktionary REST API with a default language subdomain, providing context beyond annotations. It doesn't mention rate limits or pagination, but given annotations, 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 a single sentence that front-loads the action ('Fetch the Wiktionary REST page summary') and includes parameters inline. Every word contributes meaning; there is no redundancy 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?

Given the tool's simplicity (2 parameters, no enums, output schema present) and thorough annotations, the description covers purpose, parameters, and default behavior. It enables correct selection and invocation without gaps.

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

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

Schema has 0% description coverage, so the description must explain parameters. It clearly defines 'word' as the term to look up and 'lang' as the language subdomain (default en), adding semantic meaning that the schema (only names and types) lacks. This fully compensates for the lack of schema descriptions.

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

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

The description clearly states the tool fetches a Wiktionary REST page summary (title, extract, thumbnail) for a word on a specified language subdomain, defaulting to English. This specificity distinguishes it from sibling tools like 'definition' or 'etymology' which likely provide more detailed or different content.

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

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

The description implies the tool is for fetching brief summaries from Wiktionary but does not explicitly state when to use it over alternatives like 'definition' or 'etymology'. There is no mention of when not to use it or any prerequisites.

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 mutability (readOnlyHint=false), idempotency, and non-destructive nature. Description adds value by clarifying the row is deactivated not deleted, and that historical events remain accessible via 'recent_alerts'.

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

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

Two concise sentences that front-load the action and cover key constraints. 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?

Covers purpose, ownership, and effect on data. Absence of output schema means return value is not described, but for a simple mutation tool this is acceptable.

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

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

Schema provides 100% coverage for the single parameter 'id' with its description. The description adds no extra semantic beyond 'by id', 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 verb 'Cancel' and resource 'subscription by id', with explicit ownership constraint. Distinguishes from sibling tools like 'subscribe' (creation) and 'list_subscriptions' (listing).

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

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

Implies usage context by noting ownership enforcement and deactivation behavior, but does not explicitly state when to use this tool versus alternatives like 'subscribe' or '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, open-world, and idempotent hints, and the description adds significant behavioral context beyond that: the exact verdict vocabulary, the crucial caveat that could_not_verify means the check failed and must not be treated as evidence, and the distinction between could_not_verify and unsupported. It also mentions source routing and citations, which are not visible in annotations.

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

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

The description is long but every sentence earns its place: query examples, usage rule, routing logic, verdict breakdown, critical caveat, and the note that it replaces multiple calls. It uses clear labels ('IMPORTANT for callers') and a well-organized flow, maintaining readability despite its length.

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

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

With no output schema, the description fully explains the return value: verdict categories, the actual grounded/structured value with a pipeworx:// citation, and reasoning. It also covers the two error-like states (could_not_verify and unsupported) and their distinct meanings, making the tool's behavior complete for an agent to correctly interpret results.

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

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

Schema coverage is 100%, but the description enriches both parameters: it gives concrete examples for claim and explains the semantic meaning of tolerance_pct (percent deviation threshold, overrides wording-implicit tolerance, use 1–2 for hallucination detection, default capped at 5). This adds practical guidance beyond the bare schema definitions.

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

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

The description opens with explicit natural-language query examples and a direct statement: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by explaining a two-path routing (SEC EDGAR fast path vs. grounded pipeline) and explicitly mentions it replaces 4–6 sequential calls, making the exact function and scope unmistakable.

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

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

It states precisely when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives clear routing rules for company-financial claims vs. any other factual claim, and clarifies what the different verdicts mean, providing strong usage context. Although it doesn't name alternative tools, the guidance is explicit and detailed.

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