Lobsters

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral context: default model (Workers AI Llama-3.3-70b, free), requirement of _apiKey for Anthropic, return structure (per-model score, confidence, signals, raw_response), and that it probes 'one or more LLMs'. 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 4 sentences, front-loaded with the main purpose and scoring mechanism. Each sentence adds essential information without redundancy or fluff. It efficiently covers what, how, returns, and use cases.

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

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

Given the complexity of 4 parameters and no output schema, the description is thorough: explains inputs, default model, optional Anthropic key, return structure, and use cases. The annotations cover safety. Nothing essential is missing.

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

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

All 4 parameters have descriptions in the schema (100% coverage), and the description adds value by explaining their purpose in context: 'entity' as the thing to ask about, 'models' lists supported values, '_apiKey' for Anthropic billing, 'context' for disambiguation. It also clarifies default behavior when models is omitted.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and returns a visibility score per model. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing specifically on AI visibility scoring.

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 specifies use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to use optional parameters like models and _apiKey. However, it doesn't explicitly state when not to use this tool or provide alternatives, though the context is clear enough.

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

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

Annotations already cover readOnly/openWorld/idempotent, lowering the burden. The description adds valuable behavioral context: it routes queries, fills arguments, returns structured answers with citation URIs, and notes it's fast and works on all tiers. It doesn't discuss failure modes, but the core behavior is clearly disclosed.

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

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

Though lengthy, the description is tightly structured and front-loaded with the most critical directive ('PREFER OVER WEB SEARCH'). Each sentence adds essential information: domain list, routing behavior, trigger phrases, examples, default status, and escalation paths. No wasted words.

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

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

For a complex tool with no output schema, this description is remarkably complete. It covers the return format (structured answer with citations), input expectations (categories, examples), operational details (fast, all tiers), and explicit comparisons to alternatives. The agent has everything it needs to decide to use this 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% with alias descriptions, so the baseline is 3. The description adds meaningful guidance on input semantics: it specifies the type of natural-language questions that fit the 'question' parameter and gives six illustrative examples, clarifying both the format and scope of acceptable inputs.

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

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

The description clearly states the tool's purpose: it routes questions to 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making it unambiguous what this tool does.

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

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

Usage guidance is exceptional: it explicitly says 'PREFER OVER WEB SEARCH' for a wide range of factual queries, provides trigger phrases ('what is', 'look up', etc.), and gives concrete examples. It also outlines when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), covering both when to use and when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds meaningful context about its experimental nature, the possibility of candidate routing improvements, and that it falls back to nothing (fully functional). This goes beyond the annotation baseline.

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

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

The description is somewhat verbose but front-loaded with essential information ('Beta version of ask_pipeworx') and each sentence adds contextual value. It could be trimmed slightly without loss, but remains appropriately 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?

Despite lacking an output schema, the description references the same response shape as ask_pipeworx, providing sufficient context. It covers the experimental purpose, current state, and usage instructions, making it complete for a query tool with safe annotations.

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

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

Schema description coverage is 100%, with all parameters well-documented as aliases for question. The description adds no additional parameter information, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a beta router identical to ask_pipeworx but with experimental improvements, distinguishing it from the stable sibling. It specifies the verb ('use it exactly like ask_pipeworx') and resource (universal router with same tools and response shape).

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 it ('when you want the newest routing') and clarifies that it currently matches ask_pipeworx. It references the stable alternative indirectly but does not explicitly state when not to use it, such as a preference for the stable version in production.

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 the exact extraction behavior, the structured return format with evidence and confidence, and a detailed list of refusal reasons. It also mentions the cost of one extra LLM call, which is valuable operational context not encoded 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?

Despite its length, every sentence earns its place: purpose, mechanism, output format, refusal handling, usage guidance, and cost tradeoff. It is front-loaded with the core purpose and structured logically, making it information-dense without unnecessary filler.

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

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

The description covers the full behavioral contract: what it returns, when it refuses, why it exists, and how it compares to siblings. Given no output schema, it compensates by detailing the return shape and refusal types, making it complete for an agent to select and invoke correctly.

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

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

The schema already describes the question parameter and aliases with 100% coverage, so the baseline is 3. The description adds meaning by explaining that the question is used for routing to the right tool and filling arguments, giving deeper context about how the parameter drives behavior.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb ('EXTRACTS the answer') and resource ('what the tool result contains'). It distinguishes itself from sibling ask_pipeworx by explaining it extracts verbatim evidence and may refuse when the data doesn't directly answer.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. It also gives a clear alternative: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff of an extra LLM call.

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

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

The description details behavioral traits beyond annotations: low-confidence resolution short-circuit, closed market handling, wide-spread warnings, cancellation rule parsing, and fallback mechanisms for news. Annotations already indicate safe read-only, but the description adds rich behavioral context.

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

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

The description is long but well-organized with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), front-loading the purpose. 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?

Despite no output schema, the description fully explains return values, edge cases, safety mechanisms, and resolution rules. It is comprehensive for the tool's complexity.

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

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

With 100% schema coverage, the description adds substantial meaning by explaining input formats (slug, URL, question text), depth options, and include_raw behavior. It also elaborates on response shapes and important fields.

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'), resource ('Polymarket bet'), and outcome ('evidence packet + market-vs-model comparison'). It distinguishes the tool from siblings like polymarket_edges by emphasizing comprehensive data fan-out.

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 ('should I bet on X', 'what does the data say about Y') and classifiers, but does not explicitly state when not to use this tool or mention alternative tools.

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

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

Annotations declare readOnly, idempotent, and openWorld. The description adds substantial context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, result sorting by primary metric, return of citation URIs, and efficiency claim. No contradictions, and it significantly aids understanding of tool behavior.

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

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

The description is a single, front-loaded paragraph with example queries. Every sentence adds distinct value: triggers, data sources, behavior, return format, and efficiency. No redundancy or fluff, making it highly concise and well-structured.

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

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

Despite no output schema, the description explains return structure (paired data + citation URIs), sorting, and data sources for each entity type. It covers all key aspects needed for usage, including the number of entities and data freshness. Given tool complexity, 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?

Schema covers both parameters (type with enum, values with min/max items and descriptions). The description adds meaning: for type, it explains what data each enum value retrieves; for values, it clarifies format (tickers/CIKs for company, drug names for drug) and gives examples. This adds value beyond the schema, though the schema already provides basic descriptions.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2-5 entities, provides natural language triggers ('Compare X and Y', 'X vs Y'), and distinguishes itself from sequential single-pack lookups, covering the specific verb+resource and differentiation from 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?

It explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries for comparing or ranking. It implies when to use (comparison) and when not (single entity), and identifies the alternative (sequential lookups), providing 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?

Annotations provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description enriches these with extensive behavioral details: account/paid-tier requirements, parallel decomposition, gap[] handling ('never invented'), contradictions[] on standard/thorough, semantic excerpting, hop fields, citation_uri fetchability, and expected latency. Nothing in the description contradicts the annotations.

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

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

The description is long, but every major block serves a purpose: account prerequisite, source scope, disambiguation from siblings, depth behavior, return packet, citation guarantees, and timing. It is structured as a dense paragraph with semicolon-separated clauses rather than bullets, which slightly hurts scannability, but given the tool's complexity it earns a 4 rather than a 3. It is not bloated with fluff.

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

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

For a research tool with no output schema, the description compensates fully by detailing the return structure (verbatim evidence + confidence + source + fetched_at), the gap[] and contradictions[] fields, citation_uri semantics, hop field, depth modes, latency ranges, and the explicit note about semantic excerpting. Combined with rich sibling differentiation and prerequisite info, the agent has all the context needed to select and invoke this tool correctly.

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

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

The input schema already covers 100% of parameter descriptions, so the baseline is 3. The description adds meaningful semantic nuance by explaining what depth levels produce (quick=3 facets, standard=5 with gap-recovery, thorough=8 with lead-chasing) and stating that 'question' accepts broad/multi-part natural language because decomposition is the point. This goes beyond the schema's terse parameter 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 a specific, action-oriented statement: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It clearly identifies the resource (structured data + tool routing), the process (decompose into facets, parallel routing), and the output (findings packet). It also distinguishes itself from siblings by explicitly contrasting with ask_pipeworx and by stating 'this is NOT open-web 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?

The description is exemplary in usage guidance: it says to use ask_pipeworx if not signed in, for a single lookup, and for breaking/colloquial current-news topics. It also explains when deep_research is the right choice ('broad/multi-part questions over structured data') and mentions alternative tools for other scenarios. No other sibling tool is left as a confusing alternative.

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

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

Annotations indicate readOnly and idempotent hints, which are consistent with the description. The description adds transparency beyond annotations by detailing the output format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.'

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 is front-loaded with the purpose. It contains a long list of data domains, which is useful but slightly verbose. Overall, it efficiently communicates key 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?

Despite having no output schema, the description compensates by clearly describing the output (tool names, descriptions, full schemas) and the behavior (top-N relevance, ready-to-call results). It is complete for a discovery tool with good annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing example queries (e.g., 'analyze housing market trends'), explaining alias parameters, and noting the limit default and max (20, max 50), which is already in schema but re-stated with context.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes itself from sibling tools by stating to 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and provides a clear directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description discloses all key behaviors beyond the annotations: it fans out across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specifies exact return fields (cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents with sunset caveat, news via GDELT→GNews fallback, LEI). It also notes the patent sunset May 2025 and the need for ticker or CIK. 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 information-dense but presented as one paragraph. It front-loads with examples and key guidance, then details the data sources and returns. While efficient, it could benefit from bullet points or clearer separation of key points to improve scanability. However, it earns its space with no 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 complexity (multiple data sources, returns many fields, no output schema) the description is thorough. It covers all sources, what is returned, the patent sunset issue, the fallback for names, and the parallel execution aspect. It provides a complete mental model for the tool's capabilities and limitations.

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 adds significant meaning: explains that 'type' is currently limited to 'company' with future support planned, and that 'value' accepts ticker or zero-padded CIK but not names, with a reference to resolve_entity. This goes beyond the schema's simple type/description.

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

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

The description explicitly states the tool's purpose: to provide a full cross-source profile of a US public company in one call. It provides multiple example queries and distinguishes itself from sibling tools like resolve_entity by specifying that it should be preferred over chaining individual lookups. The verb 'profile' and resource 'entity' are clearly defined.

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

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

The description gives clear when-to-use guidance: 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' It also explicitly states when not to use it: if the user only has a name, use resolve_entity first. This provides excellent decision support for the AI agent.

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 destructive and idempotent behavior. The description adds no further behavioral details beyond the fact that it deletes a memory; it does not clarify what happens if the key does not exist or if there are any side effects. With annotations covering the key safety traits, the minimal extra context suffices.

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: the first states the action, the second gives usage guidance. No extraneous information, and the key information is front-loaded.

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

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

Given the low complexity (single required parameter, no output schema, no nested objects), the description covers the essential aspects. It could mention the expected behavior on success or failure (e.g., whether it returns anything), but the lack of an output schema reduces the need. Overall, it is adequately informative for an agent to use 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 provides 100% coverage with a description for the 'key' parameter ('Memory key to delete'). The tool description adds no additional meaning beyond what the schema already states, so the baseline score of 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?

Clearly states the action: delete a memory by key. Distinguishes itself from sibling tools 'remember' and 'recall' by pairing with them, making its role as the deletion function explicit.

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

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

Provides explicit contexts for use: stale context, completed task, clearing sensitive data. Mentions alternative or complementary tools ('remember' and 'recall'), guiding 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 already declare readOnlyHint and idempotentHint. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard llms.txt format. 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 concise with no wasted sentences. It is front-loaded with purpose, followed by process, then use cases. 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?

Despite no output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt'). It covers input, process, and output adequately for a simple 2-parameter tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond the schema; it says 'for any URL' and implies max_links, but nothing beyond schema info.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and target. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing specifically on llms.txt generation.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. While it doesn't mention when not to use or alternatives, the use cases provide 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and side effects. The description adds value by specifying the return fields and data source, but does not mention any additional behavioral traits (e.g., rate limits, authentication).

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, no extraneous information. The primary action and return fields are front-loaded, making it easy for an agent to parse quickly.

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 no parameters, a simple return, and an output schema (per context signals), the description adequately covers what the agent needs to know: source and return fields. Could mention ordering or limits, but not necessary given the tool's simplicity.

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

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

The input schema has no parameters, and schema description coverage is 100%. The description does not need to explain parameters. Baseline of 4 is appropriate for zero-parameter tools.

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

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

The description uses a specific verb ('Get') and resource ('trending stories from Lobsters'), and lists the returned fields (title, URL, score, comment count, tags). It clearly distinguishes from siblings like get_newest (newest vs trending) and get_story (single story vs list).

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

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

The description implies use for trending content but does not explicitly state when to use this tool versus alternatives like get_newest or get_story. No exclusion criteria or context is provided.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds minimal behavioral context. It confirms the tool returns specific fields but does not disclose potential rate limits or other traits beyond what annotations indicate.

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

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

The description is two concise sentences, front-loaded with the core purpose, and contains no extraneous information. 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?

For a simple parameterless tool with an output schema, the description is complete. It specifies the source and return fields, which is sufficient for an agent to understand usage.

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

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

There are no parameters, and schema description coverage is 100%, so the description does not need to add parameter details. It adds no extra meaning beyond the schema, which is adequate for a parameterless tool.

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

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

The description clearly states the tool retrieves the latest stories from Lobsters and specifies the return fields (title, URL, publication time, score, tags). It is specific and distinct from siblings like get_story, though it does not explicitly contrast with get_hottest.

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 such as get_hottest or other story-related tools. No usage context or exclusions are given.

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, and non-destructive hint. Description adds return details (nested comments, fields) but no additional behavioral 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?

Single sentence, front-loaded with key action and resource. 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?

Tool is simple (one param, output schema exists). Description covers purpose and return value sufficiently. No missing information for a straightforward fetch operation.

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. The description adds an example format but does not significantly enhance understanding beyond the schema. Baseline score of 3.

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

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

Description clearly states verb ('Fetch'), resource ('a single story and all its comments'), and output fields. It distinguishes from sibling list tools (e.g., get_hottest) by specifying 'single story'.

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

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

Usage is implied (need a story ID), but no explicit when-to-use, when-not-to-use, or alternatives among siblings are mentioned. Adequate but not explicit guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already cover safety and behavior. The description adds that it returns specific fields (titles, URLs, scores, tags), but does not disclose edge cases (e.g., exact match, pagination). With rich annotations, this is adequate.

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, direct sentence that immediately conveys the purpose and expected output. No wasted words.

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

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

Given the presence of an output schema (implied from context signals) and simple parameter set, the description covers the essential points. Could mention search behavior (exact vs fuzzy) but not required.

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

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

The input schema has 100% description coverage, and the description repeats the tag parameter with examples. No additional meaning beyond the schema; baseline score of 3 is appropriate.

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

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

The description clearly states the verb ('search') and resource ('stories by tag'), and provides examples of tags. It distinguishes from sibling search tools by specifying the tag-based filtering and return fields.

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 like search_within, deep_research, or other story-related tools. The description does not mention when not to use it or provide selection criteria.

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, destructiveHint. Description adds context about return fields (id, type, params, created_at, last_fired_at, fire_count) and default behavior (lists active only). Consistent 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?

Two sentences, front-loaded with purpose and return fields, followed by usage guidance. 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?

For a simple read-only list tool with one optional boolean parameter, the description covers purpose, return data, usage context, and parameter hint. No output schema needed; annotations cover safety.

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

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

Schema coverage is 100% with detailed description for 'include_inactive'. The tool description does not add significant meaning beyond the schema, but it does imply the parameter's purpose by mentioning 'active subscriptions' and usage for cancellation.

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 'list' and the resource 'subscriptions' with scope 'caller's active'. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by specifying it returns IDs for cancellation and review purposes.

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

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

Explicitly mentions when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel'. Implicitly suggests not to use for creation/modification, though alternative tools are not named.

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 (which only indicate mutation via readOnlyHint: false), the description discloses key behaviors: 'Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed,' 'Rate-limited to 5 per identifier per day,' and 'Free; doesn't count against your tool-call quota.' These operational details are not inferable from annotations and significantly help the agent anticipate consequences.

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

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

The description is lengthy but every sentence carries unique, actionable information. It is front-loaded with the core purpose, followed by conditional usage, exclusions, and operational details. No empty filler; the length is justified by the tool's complexity and the need to prevent misuse (e.g., filing feedback for other MCP servers).

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 multiple usage modes (filing feedback, checking a previous report via claim_token), exclusions, rate limits, and no output schema, the description covers all necessary aspects. It even explains the workflow for anonymous filing and later retrieval. The tool's complexity is high, and the description fully addresses it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context for the claim_token parameter by explaining when it is issued ('Filing without an account') and how to use it to retrieve status updates, which goes beyond the schema's 'Read the reply' phrasing. The other parameters (type, context, message) are already well-described in the schema, so no further compensation is needed.

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

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

The first sentence clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (Pipeworx team) and action (tell), and the following lists of use cases (bug, feature, data_gap, praise) distinguish it from sibling tools like ask_pipeworx. It also explicitly scopes what it does not cover (tools from other MCP servers), further removing 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 gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is a textbook example of usage differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: it is self-aggregating from CF analytics-engine, contains no PII, uses (pack, tool, count) data, and is cached 5min-1h. 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?

Three concise sentences: first declares core functionality, second lists use cases with bullet-like structure, third provides technical details. No wasted words, front-loaded with the most important information.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the response shape (top tools, top packs, total call volume, data structure (pack, tool, count)). It lacks explicit return format, but is sufficient for an agent to understand what it gets.

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

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

The schema has 100% coverage with one parameter 'window' and an enum description. The description adds value by explaining how shorter vs longer windows affect interpretation ('shorter windows surface what's hot right now; longer windows show steady-state demand'), going beyond the schema's basic description.

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

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

The description clearly states it returns top tools, top packs, and total call volume from AI agent calls, with a specific verb ('returns') and resource ('Pipeworx Trending'). It distinguishes itself from sibling tools like 'discover_tools' and 'get_hottest' by focusing on real-time agent usage signals.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical choices, checking alignment). It implies when to use (trend analysis) but does not explicitly mention alternatives or when not to use. The use cases are clear and actionable.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral detail: scanning logic (monotonicity violations, partition-sum checks), semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check against live CLOB depth, and response structure. No contradictions with annotations.

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

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

The description is well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and presents information in order of importance. While somewhat verbose, every sentence provides necessary detail for a complex multi-mode tool. Slightly longer than ideal but justified by the tool's intricacy.

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 fully documents the response format (opportunities[] fields, partition_check fields, fill_check fields). It covers all modes, edge cases (placeholders, low similarity), and links to related tool (polymarket_fill_risk) for custom sizing. No gaps remain for an agent to understand invocation and 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 description adds significant meaning beyond schema: explains the difference between event and topic modes, provides examples of valid values (slugs, URLs, seed questions), and describes behavior changes based on parameter selection. This enables the agent to choose correctly.

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' and distinguishes three modes (trending_scan, event, topic) with specific usage examples. It identifies the resource (Polymarket markets) and action precisely, making the purpose unmistakable.

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

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

Explicitly provides when to use each mode (no args for trending_scan, event for specific market with example slugs, topic for cross-event scanning with seed questions). Includes recommendations ('event recommended for a specific market'), explains limitations (cross-event catches patterns single-event misses), and warns when not to trade (realizable_edge_pp ≤ 0).

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

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

The description discloses extensive behavioral traits beyond annotations: caching at KV level (1h keyed on knobs), diagnostic information on why segments may be empty, 24h-move warning when recent move exceeds edge, and detailed model family mechanics. Annotations (readOnlyHint, idempotentHint) are consistent; 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 information-rich, front-loading purpose and segments. While lengthy, every sentence adds value. Minor points: could be slightly more structured with bullet points, but overall efficient.

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

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

Given the tool's complexity (3 segments, 9 parameters, diagnostics, caching), the description is remarkably complete. It covers response structure, field descriptions (edge_pp_net, kelly_fraction, etc.), and runtime behavior even without an output schema.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds significant meaning beyond schema, such as real-world slippage context for slippage_pp, how min_partition_leg_kelly interacts with partition arbs, and tradeable-edge filter behaviors for min_liquidity and max_spread_pp.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx's proprietary signals and the "what should I bet on today" 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?

The description provides explicit guidance on how the tool discovers opportunities, explains tradeable-edge knobs with usage suggestions (e.g., bumping slippage for thin partitions), and notes that Fed bets are excluded. However, it does not explicitly state when to prefer this tool over siblings like polymarket_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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, establishing safety. The description adds substantial behavioral context: response structure (tracked, expired, snapshot_dates arrays), field semantics (trend, decay_pp_per_day), expiration meaning, and limitations (60-day TTL, decay from daily closes). 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 detailed but well-organized, with response structure front-loaded. Each sentence adds value. Slightly verbose but clear; no wasted content.

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

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

Despite having no output schema, the description comprehensively explains the output format, including three arrays with field details and limitations. It covers all expectations for a two-parameter tool with rich output.

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

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

Schema coverage is 100% (both parameters well-described in schema). The description restates parameter defaults and values (days: default 14, max 30; window: 24hr|1wk|1mo) but adds no new semantic information 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 the tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It answers specific questions like 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old edges, distinguishing it from sibling tools like polymarket_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 implies usage (when you need edge persistence/decay info) but does not explicitly state when not to use it or suggest alternative tools. There is no direct guidance on choosing between this and siblings like polymarket_edges or polymarket_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, idempotentHint, etc. The description adds critical behavioral details: forced_directional_risk in basket mode, clamping of size_usd, and the risk of partial fills. No contradictions with annotations.

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

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

Description is fairly long but well-structured with clear sections: purpose, mode explanations, usage guidance. Every sentence adds value; no fluff. Could be slightly tighter but effective.

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

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

Tool is complex with two modes and many return fields. Since no output schema exists, description must cover returns. It does: lists all returned values for both modes, explains risk mechanisms, and provides usage thresholds. Complete for the complexity level.

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

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

Schema coverage is 100%, baseline 3. Description adds semantic value by explaining mode selection (market vs event), meaning of size_usd per mode, and default side logic for baskets. These details enhance 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?

Description clearly states the tool checks realizable vs theoretical edge using live order book depth, and distinguishes two modes (single-market and basket). It is not a tautology and differentiates from sibling tools like polymarket_arbitrage.

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

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

Explicitly advises to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Explains the risk of partial basket fills converting arb into unhedged directional positions, providing clear when-to-use context.

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

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

The description reveals extensive behavioral traits: it details the response structure including leg-by-leg prices, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. This goes well beyond the annotations (readOnlyHint, idempotentHint) by explaining safety fields and why spreads may be invalid.

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 detailed but front-loaded with the core purpose. While it is lengthy, every sentence adds necessary context for a complex tool. Some redundancy exists (e.g., repeated warnings about pre-mapped topics), but overall it is well-structured.

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

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

Given the complexity of cross-venue spread analysis and the lack of an output schema, the description fully explains the response fields, safety indicators, and limitations. It covers all relevant aspects, making the tool self-contained 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?

The input schema covers all 3 parameters with descriptions, achieving 100% schema description coverage. The tool description adds value by listing the exact topic shortcuts and clarifying override behavior for explicit tickers, providing context beyond the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes and warns that pre-mapped topics often return compatibility warnings, which distinguishes it from siblings like polymarket_arbitrage or polymarket_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 explains the two usage modes (topic shortcuts vs explicit tickers) and notes that most pre-mapped topics are currently not tradeable due to compatibility_warning. However, it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: scoping to identifier, listing all keys when key omitted, and pairing with remember/forget. 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?

Three sentences, front-loaded with the core action, no redundant information. Each sentence adds value: what it does, when to use it, scoping, and pairing with related tools.

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 is complete. It covers purpose, usage guidelines, behavioral traits, and parameter behavior, leaving 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 a clear description of the key parameter. The description reinforces the parameter's behavior (omit to list all keys) and adds context about key types (ticker, address, notes) but does not provide significant new semantic 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 retrieves a value saved via remember or lists all keys, using specific verbs (retrieve, list) and the resource (saved values/keys). It differentiates from sibling tools 'remember' and 'forget' by naming them and describing the pairing.

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

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

The description explicitly states when to use the tool ('look up context... without re-deriving it from scratch'), provides scoping information, and pairs with remember and forget as alternatives. It offers clear guidance on usage context and exclusion of other 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 readOnly, openWorld, idempotent, non-destructive. Description adds behavioral detail: mark_read:true flags events as read, affecting next call's results. 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?

Four concise sentences with front-loaded purpose. Every sentence provides essential information: purpose, return fields, filter options, mark_read effect, and alternative endpoint. 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?

Despite lacking an output schema, the description details return fields (source, citation_uri, payload) and parameter usage. Covers all necessary context for a tool with simple inputs and outputs. Alternative endpoint adds completeness.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by explaining filter usage (example 'sec_8k', ISO timestamp) and clarifying mark_read behavior. Enhances understanding 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 'Pull fired events from your subscription feed' and specifies key return fields (source, citation_uri, raw payload). While it doesn't explicitly differentiate from sibling tools like 'list_subscriptions', the context of 'recent alerts' is specific enough to avoid confusion.

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 guidance: 'Polls work fine' and suggests an alternative HTTP endpoint for scripts/dashboards. Does not contrast usage with sibling tools, but the alternative endpoint is a clear when-to-use hint.

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

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

Annotations already indicate readOnly, idempotent, etc. The description adds rich behavioral detail: fans out to SEC EDGAR, GDELT→GNews, USPTO; describes fallback logic; mentions output structure with changes[], total_changes, citation URIs. No contradictions with annotations.

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

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

The description is a single dense paragraph that front-loads example queries. Every sentence adds value, but it could be slightly more structured (e.g., bullet points for sources). Still concise and informative for its complexity.

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

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

Given three parameters, no output schema, the description covers return structure, fan-out logic, fallback, and limitations (USPTO soft-fail). It provides enough context for an agent to understand when to call and what to expect without needing additional documentation.

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. The description adds further context: examples for 'since' (ISO date, relative shorthand), recommended default, and explanation for 'value' (ticker or CIK). For 'type', it notes only 'company' supported. Adds significant 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?

The description uses concrete example queries and explicitly states the purpose: a change feed for a company over a time window. It distinguishes from sibling 'entity_profile' for static profiles, making the tool's unique purpose very clear.

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

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

The description provides explicit when-to-use (recent changes over a window) and when-not-to-use (use entity_profile for static profiles). It also explains fallback behavior and soft-fail for USPTO, guiding correct invocation.

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?

Annotated with idempotentHint=true, no contradiction. Description adds critical context: key-value scoped by identifier, persistence differences (authenticated vs anonymous, 24-hour TTL). No unaddressed side effects.

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

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

Five sentences, front-loaded with main purpose, no fluff. Every sentence adds necessary context: purpose, when, storage details, pairing.

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

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

Given the simple tool (2 string params, no output schema), the description is fully complete. Covers purpose, when, how, behavioral traits (scoping, persistence). 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 good descriptions. Description adds value by providing examples of keys and values, and clarifying that value is arbitrary text. Reinforces context but schema already covers basics.

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: 'Save data the agent will need to reuse later' with specific examples of what to store (resolved ticker, target address, etc.). It distinguishes from siblings by explicitly mentioning 'recall' 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?

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides pairing guidance: 'Pair with recall to retrieve later, forget to delete.' No ambiguity.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral context beyond annotations: it mentions internal cascading through multiple endpoints, graceful degradation when external sources are unavailable, and explicit reporting of unresolved identifiers. It also explains enrichment behavior and citation format, providing a transparent picture of side effects and edge cases.

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

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

The description is long but information-dense. It opens with relatable user queries, states the core purpose, then breaks down supported types with concrete details. Each clause contributes value: supported identifiers, source attribution, unresolved handling, graceful degradation, and internal behavior. The structure is logical and scannable, with no 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 must explain return values, which it does by listing the specific identifiers for each type (CIK, ticker, LEI, FIGI for company; RxCUI, ingredient, brand for drug). It also addresses error/edge behavior (unresolved list, degradation if external APIs down) and justifies the tool's internal complexity. For a 2-parameter tool, this is comprehensive.

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%, providing a baseline of 3. The description adds meaningful semantics: it explains the difference between 'company' and 'drug' types, gives accepted input formats for company (ticker, CIK, or name) and drug (brand or generic), and includes specific examples for the value parameter. It enriches understanding beyond the schema's terse 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 clearly states the tool's function: resolving user-spoken names to canonical/official identifiers. It provides specific example queries, names the resource type ('entity'), and distinguishes itself from sibling tools by framing the output as IDs required by other tools. This is a specific verb+resource with clear differentiation.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use condition. It also notes the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly name alternative tools for scenarios not involving ID resolution (e.g., entity_profile for detailed history), so it lacks explicit exclusion guidance.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds that it probes each entity with another tool (ai_visibility_check) and returns a ranked list with specific fields (score, confidence, signal density). 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?

Three sentences: action, process, use case and output. Front-loaded, no waste. Each sentence provides essential information.

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

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

Explains output structure and process. Lacks edge cases but sufficient for typical use. Annotations cover safety, so missing error handling 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?

Input schema has 100% description coverage, baseline 3. Description adds context: 'first entry treated as the subject for narrative' and usage hint for 'models' parameter ('Omit for just workers-ai'). This enhances understanding 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?

The description clearly states the tool compares AI visibility across multiple entities, using specific verbs like 'Compare', 'Probes', 'ranks', 'surfaces'. It distinguishes itself from sibling 'ai_visibility_check' (single entity) and 'compare_entities' (general comparison) by focusing on AI presence.

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

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

Explicitly mentions use for competitive AI-marketing audits and gives an example question. Implicitly suggests using 'ai_visibility_check' for single entities. Could explicitly state when not to use, but the 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about composite fan-out, partial failures, bundlephobia timeout, and sources_failed listing.

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 starts with the main composite purpose, then details usage, returns, and limitations. Could be slightly shorter but remains efficient.

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

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

No output schema exists, so description compensates by detailing the return summary block fields (is_latest, license, etc.), per-advisory detail, links, recent alternative versions, and graceful handling of partial failures.

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

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

Schema description coverage is 100% and provides clear descriptions for both parameters. The description adds helpful context like scoped packages and defaulting to latest version, going 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 is a composite check for npm packages, combining deps.dev and bundlephobia. It distinguishes from siblings by specifying the ecosystem (NPM only) and the exact purpose (safety, popularity, size).

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 when to use it (e.g., 'is X safe / popular / small') and notes that other ecosystems (PyPI, Maven, etc.) should use deps.dev:version directly. Also mentions partial failures and graceful degradation.

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 context beyond annotations: model details (BGE-base-en), window size (500-char overlapping), cap (200K chars with truncation flag), and offset-based verification. All consistent with idempotent and read-only hints.

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 purpose, followed by usage guidance, then technical details. No wasted words; 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?

No output schema, but description clearly states return type (top-N passages with offsets and similarity scores). Covers input constraints, behavior, and pairing with sibling tools. Complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. Description enhances with examples for query, default/range for limit, and max chars for text, adding practical value.

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?

Clear verb+resource: 'semantic search INSIDE a fetched record'. Distinguishes from siblings by pairing with ask_pipeworx_grounded and contrasting with whole-document usage.

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 the record is too big to cram into the prompt'. Provides usage scenarios but lacks explicit when-not-to-use statements.

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 authentication requirements, account restrictions, delivery verification steps, SMS daily cap, and webhook auto-disable after failures. However, the idempotentHint annotation (true) is not supported by the description, which implies each call creates a new subscription, creating a minor contradiction.

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

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

The description is well-structured with clear sections for types and delivery, front-loading the main purpose. It is slightly dense but every sentence adds value, though it could be trimmed slightly 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?

Covers all main aspects: supported types, parameter formats, delivery channels, return value, and important limits. Does not mention error handling or idempotency, but given the tool's complexity and no output schema, it provides sufficient context for successful use.

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

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

The description adds significant value beyond the input schema by providing concrete examples for each subscription type (e.g., 'sec_8k' with items), clarifying nested parameters, and detailing delivery constraints like phone verification and webhook signing. Schema coverage is 100%, and the description compensates fully.

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 creates a proactive monitoring subscription and returns a subscription ID. It specifies the resource (live-data event stream) and distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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 context for when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account). Includes type-specific use cases and delivery channels. Could improve by stating when not to use or mentioning alternatives, but still clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the output structure (category-bucketed example questions with tool+argument shapes) and that it draws from a live catalog of thousands of tools. No contradictions with annotations.

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

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

The description is front-loaded with the primary purpose and includes multiple example queries. While slightly long, every sentence adds value. It is well-structured with clear sections.

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 simple purpose (onboarding) and lack of output schema, the description is fully complete. It covers when to use, how to use (with/without topic), what it returns (category-bucketed examples), and even mentions the live tool catalog.

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

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

Schema coverage is 100% and the description provides additional meaning: it lists example topic values (finance, pharma, etc.) and explains the behavior difference between omitting versus passing a topic. This fully compensates for any missing schema detail.

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

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

The description uses a specific verb ('suggest') and resource ('questions'), clearly identifying it as the onboarding entry point. It distinguishes this from sibling tools like 'ask_pipeworx' (direct Q&A) and 'discover_tools' (tool discovery) by stating it returns example questions with tool shapes for getting started.

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

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

The description explicitly states when to use this tool: 'when you do not yet know what Pipeworx can do' and 'to learn how to call the meta-tools'. It also provides conditional guidance: call with no arguments for full spread, or pass a topic to focus. This is exemplary.

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

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

Adds value beyond annotations by explaining that the row is deactivated (not deleted) and historical events remain available. Consistent with destructiveHint=false. Does not mention idempotency from idempotentHint=true, but overall informative.

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 with no wasted words. Purpose is front-loaded, and critical usage details are included efficiently.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, and behavioral outcome. Lacks explicit mention of return value or success indication, but sufficient for agent invocation.

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

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

Schema coverage is 100% with the id parameter fully described. The description does not add additional parameter meaning beyond what the schema provides, so baseline score of 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 clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like 'subscribe' 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 ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, which guides appropriate use. Lacks explicit when-not-to-use but provides sufficient 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the critical behavioral nuance that 'could_not_verify' means the check did not happen and must not be treated as evidence, including the verification_error{stage,detail} payload. It also explains 'unsupported' as meaning no source covers the claim. This is rich, non-obvious behavioral context that plain annotations cannot convey.

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

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

The description is long but well-structured: opening examples, usage, behavioral rules, and a clear callout for the critical 'could_not_verify' edge case. Every sentence adds value. The 'Replaces 4–6 sequential calls' line is a minor nicety but not essential; slight trimming could improve conciseness without losing 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?

Despite having no output schema, the description thoroughly explains the return value structure: verdicts (all six), the grounded or structured actual value with citation, reasoning, and the error object for failed checks. It covers the two routing paths and distinguishes ambiguous verdicts. For a complex tool with 2 parameters and no output schema, this description 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?

Schema description coverage is 100%, so both 'claim' and 'tolerance_pct' are adequately documented in the schema. The description does not add any additional parameter-level semantics beyond what the schema already states; it merely references claim types and tolerance indirectly. Baseline 3 is appropriate because the schema handles parameter explanation fully.

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 example queries ('Is it true that...', 'fact check', 'verify the claim...') and a clear verb+resource: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools by focusing on fact-checking with a verdict, and enumerates the two internal paths (SEC EDGAR for financial, grounded pipeline for everything else). This makes the purpose unmistakable.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' This gives clear when-to-use guidance. It also explains the two sub-paths (financial vs. any other claim), but it does not name alternatives or provide when-not-to-use exclusions relative to sibling tools like ask_pipeworx_grounded. Hence 4 rather than 5.

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