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 declare readOnlyHint, idempotentHint, and openWorldHint. The description adds meaningful behavioral detail: internal routing, argument filling, stable citation URIs, one-answer-per-subunit defaults, the 'multi' option, and explicit caution against overusing 'multi'. No contradiction with annotations.

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

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

The description is dense and front-loaded with the primary use case, then alternatives, then caveats. A few sentences are somewhat redundant or meta, such as the system-prompt recommender and the repeated caution against 'multi', but overall the length is justified for a router tool.

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

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

Given no output schema and only one meaningful parameter, the description covers scope, behavior, output type (citations, not full pages), routing, alternatives, and caveats. An agent has enough to select and call this tool correctly in most factual-query scenarios.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for a natural-language question. The description adds practical semantics by showing example questions and explaining how to express compound requests and when to add 'multi' for more nuance, going slightly 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 defines the tool as a general-purpose router that answers factual questions by selecting among 5,767 tools across 1,506 sources and returning structured answers with citation URIs. It explicitly contrasts itself with web search and sibling tools, making its role unmistakable.

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

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

The description gives explicit when-to-use guidance with trigger phrases like 'what is', 'look up', 'get the latest', and numerous concrete examples. It also names alternatives — ask_pipeworx_beta, ask_pipeworx_grounded, deep_research, and web_search — with conditions for choosing each one.

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

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

Beyond the annotations, the description discloses the beta status, the live candidate-routing behavior, the current absence of an active candidate, and the fact that this is a full working router rather than a fallback. This gives the agent a clear and honest picture of what to expect.

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

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

The core identity and current-state information are front-loaded, and each sentence adds distinct value. The exact tool count and retirement date are slightly granular, but they contribute to the transparency without feeling like 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?

For a single-question router with no output schema, the description covers current behavior, relationship to the stable tool, response-shape identity, experimental caveats, and fallback semantics. An agent has enough information to choose 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 provides 100% description coverage for all six parameters, including the aliases for question, so the description adds little parameter-level detail. The statement that it takes the same arguments as ask_pipeworx is useful context but does not need to restate 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 immediately identifies the tool as the beta version of ask_pipeworx and explains that it is the same universal router with the same 5,767 tools, arguments, and response shape. This makes the purpose concrete and clearly separates it from the stable ask_pipeworx through the experimental routing framing.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router to decide what merges. The note that no candidate is currently active also tells the agent that behavior presently matches ask_pipeworx exactly, which is strong usage guidance.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description goes beyond by disclosing the extra LLM call cost, the explicit refusal structure with specific refusal_reason values, and the fact that answers are extracted only from tool results. This is rich behavioral context that annotations alone do not provide.

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

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

The description is dense but every sentence earns its place: core behavior, routing mechanism, return/refusal format, usage context, and cost tradeoff. Information is front-loaded with the primary purpose stated first, then important output and usage details, then the efficiency comparison. No filler or 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?

With no output schema, the description fully explains the return shape (success object with answer, evidence, confidence, source, fetched_at) and the refusal object with all possible refusal_reason values. Combined with the use-case guidance and cost note, an agent has everything needed to invoke the tool correctly and interpret its response.

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

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

Schema description coverage is 100%, with all six parameters being aliases for 'question' and each described as natural language. The tool description contextualizes the question but adds no parameter-specific semantics beyond what the schema already provides. Baseline 3 is appropriate because the schema fully documents the parameters.

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

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

The description clearly states this is a hallucination-resistant answer mode that routes through the same tool selection as ask_pipeworx, fetches data, then extracts an answer using only the tool result. It names the resource (cross-tool grounded answering) and distinguishes itself from siblings by emphasizing evidence-grounded extraction and refusal behavior.

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

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

Explicitly states when to use: whenever an answer will be quoted, cited, or acted on and facts must not be invented (financial, legal, medical, public statements). Also names the alternative ask_pipeworx and advises preferring it for casual lookups due to the extra LLM call cost. This gives an agent clear routing guidance.

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

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

The description 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 already provide readOnlyHint and idempotentHint, but the description adds rich behavioral context: account requirement per depth tier, returns findings packet with evidence/confidence/source/fetched_at/citation_uri, explicit gaps[] for unanswerable facets, never invents data, excerpts large records semantically, and takes 15-90s. It discloses what the return packet contains and how gaps/contradictions are handled. No contradiction with annotations.

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

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

The description is long but densely informative. Every clause earns its place (account gating, sibling routing, structured-source scope, parallel decomposition, findings packet, gap behavior, depth semantics, latency). It is front-loaded with the most decision-critical constraint (account required) and the alternative routing. The only minor deduction is that the density and parentheses make it slightly harder to parse at a skim.

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 research tool with no output schema, the description covers all essentials: inputs, depth options, expected output shape, failure/gap behavior, latency, and account prerequisites. The agent knows exactly what to expect and what to tell the user, including the sibling fallback for signed-out users. Nothing critical is missing.

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

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

Schema coverage is 100% and the schema parameter descriptions already explain depth levels, so the baseline is 3. The tool description adds extra value by explaining what each depth does ('standard' adds gap-recovery hop; 'thorough' adds iterative lead-chasing) and linking depth to paid plans, which helps an agent choose correctly. Slight credit for the added decision-relevant detail, but the schema already carried most of the semantic weight.

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 ('research') plus resource ('Pipeworx's 1506 STRUCTURED data sources') and explicitly scopes what it is NOT ('this is NOT open-web search'). It differentiates itself from ask_pipeworx by conditional ('If you are not signed in, use ask_pipeworx instead') and explains the one-call multi-source parallel decomposition approach. No ambiguity about what the 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?

The description explicitly states when to use deep_research (broad/multi-part questions over structured data) and when NOT to ('For a single lookup use ask_pipeworx instead'). It even names the sibling alternative and requirement. It differentiates depth levels with concrete behavior and time expectations, giving an agent clear decision 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 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?

Beyond the readOnly/openWorld/idempotent/non-destructive annotations, the description discloses critical runtime behavior: it fans out across many sources in parallel, soft-fails when USPTO's API sunset occurs, uses a GDELT→GNews fallback, and returns sources_used/sources_failed so empty sections are understood as real 'no data'. This is far more than the annotations alone provide.

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

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

The description is long, but the complexity of the tool justifies it: with no output schema, the description must carry the return-shape, source-list, and edge-case burden. It is front-loaded with usage examples and then moves through behavior, sources, input formats, and failure semantics without meaningless filler, though a few parentheticals could be tightened.

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

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

Given the tool's high complexity, full schema coverage, and absence of an output schema, the description is unusually complete. It covers all input forms, the output sections, source-level failure behavior, the private-company result shape, and type semantics, so an agent has nearly everything needed to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it gives concrete examples for value ('AAPL', '0000320193', 'Moderna'), explains zero-padded CIK format, notes that names resolve via SEC EDGAR's company-name match, and clarifies that type accepts company/ticker interchangeably. This goes beyond the schema's bare property descriptions.

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

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

The description states a specific action and resource: it builds a 'full cross-source profile of a US public company' via multiple named sources, with concrete example queries like 'Tell me about X' and 'company profile for Microsoft'. It also differentiates itself from sibling single-pack SEC/XBRL/news lookups by explicitly preferring this tool for holistic views.

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

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

The description explicitly says to 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when a comprehensive view is requested. It also clarifies the private-company case, stating that a company with no CIK/ticker returns resolved:false with an explicit notes line rather than a bare failure.

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?

Even though annotations already mark the tool as read-only, idempotent, and non-destructive, the description adds deep behavioral detail: the token-overlap matching algorithm, pairing_unverified set in either mode, unknown metric_type legs never paired, gross (not net) spreads due to unmodeled Kalshi fees, and the precise null semantics of temporal_alignment. This is exceptional disclosure beyond anything annotations or schemas provide.

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

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

The description is long but every sentence earns its place and it is carefully structured with labeled blocks (TWO MODES, RESPONSE, SAFETY FIELDS, codes, skipped counters). The purpose sentence is front-loaded, and the dense caveats are scannable and purposeful.

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

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

With no output schema, the description fully carries the burden of explaining return values and does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility fields, temporal_alignment null semantics, fees_note, and skipped_cross counters. It also warns against over-trusting macro shortcuts, covering both functional and interpretive needs.

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, so the baseline is 3. The description adds mode semantics — how explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side — and lists all ten topic shortcuts, which meaningfully enriches the bare schema definitions.

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

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

The description opens with a specific function — cross-venue spread between Kalshi and Polymarket for the same resolving question — with a clear verb and resource. It does not explicitly name sibling tools like polymarket_arbitrage to differentiate, but the scope is unambiguous and the title reinforces the focus.

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 clearly describes two invocation modes (topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug) and when each is appropriate, and warns that most pre-mapped topics return compatibility warnings today. However, it does not explicitly contrast with sibling tools, so no explicit alternatives or exclusions are stated.

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?

Beyond the annotations, the description richly discloses behavior: graceful degradation when GLEIF/OpenFIGI fail, returning figi_candidates when a name matches multiple instruments, explicitly listing unresolved identifiers, cascading through multiple internal lookup endpoints, and labeling every identifier with its source. This goes well beyond what readOnlyHint/idempotentHint provide.

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

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

The description is dense and sometimes rambling, with long nested parentheticals that reduce readability. While the purpose is front-loaded and most sentences carry useful information, the sheer volume and repeated caveats prevent it from being concise or tightly structured.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it covers key expectations: source labels, unresolved identifiers, figi_candidates, and fallback degradation. It is nearly complete for a complex tool, though it stops short of specifying the exact output object shape or possible error conditions.

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?

Despite 100% schema coverage, the description adds substantial semantic value, especially for the 'value' parameter: it gives concrete examples (AAPL, 0000320193, 'ozempic'), warns to pass only the entity name, and explains that for bonds trailing security-class words will fail the FIGI lookup. It also clarifies what each 'type' returns beyond the enum.

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 and resource: it resolves user-spoken names to canonical/official identifiers that other tools require as input, with explicit support for 'company' and 'drug'. It clearly differentiates itself by saying 'Use FIRST whenever you have a name but need an ID', setting it apart from siblings like entity_profile or search_within.

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

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

It gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. However, it does not explicitly name alternatives or state when-not-to-use conditions relative to specific sibling tools, so it falls short of a 5.

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

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

Annotations 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.