Opencellid

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

Beyond annotations (readOnlyHint, etc.), the description adds behavioral context: exact return structure (per-model {score, confidence, signals, raw_response} + combined view), default model cost (free), and BYO key model (Anthropic). 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?

Three sentences, each earning its place: first sentence states action and output, second explains options and cost, third lists use cases. No redundant words, fully 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 tool's complexity (multiple models, scoring, optional parameters, no output schema), the description is complete: it covers purpose, parameters, return format, and ideal use cases. 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 descriptions cover all 4 parameters (100% coverage). The description adds value by explaining the default model behavior for 'models', the purpose of '_apiKey' (pass-through to Anthropic), and the disambiguation help of 'context'. This goes beyond the schema descriptions.

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

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

The description uses specific verbs ('Probe', 'score') and identifies the resource ('LLMs', 'visibility') and the output ('0-100 score per model'). It clearly distinguishes from sibling tools like scan_competitor_ai_presence by focusing on multi-model 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 provides clear usage context: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to provide _apiKey (for Anthropic) and that the default model is free. It lacks explicit 'when NOT to use' guidance, but the use cases are sufficient.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds behavioral detail by explaining that it routes to one of 5,798 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This gives an agent useful expectations beyond the annotations.

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

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

The description is long, but every section earns its place: preference directive, domain list, routing mechanism, trigger phrases, examples, and sibling routing. It is front-loaded with the most important decision rule ('PREFER OVER WEB SEARCH') and the alternative routing appears at the end. It could be marginally trimmed, but the density of actionable guidance justifies the length.

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

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

For a high-level router with no output schema, the description covers what the tool does, how it works, what it returns, and when to use alternatives. It doesn't describe exact response envelopes or failure modes, but the annotations cover safety and the description gives enough context for correct invocation. Given the scope of 5,798 tools, the coverage is strong.

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 properties documented as aliases of 'question'; the description does not need to add parameter-level detail. The schema's 'question' entry explicitly accepts natural language and the aliases. The description reinforces that the input is a natural-language question via trigger phrases, which adds minimal but sufficient 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?

The description opens with a strong directive: prefer this tool over web search for current/historical authoritative data, and explicitly states it routes questions to 5,798 tools and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_beta, ask_pipeworx_grounded, and deep_research for other use cases. The purpose is 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 trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and concrete examples. It also names the exact alternatives and the conditions for choosing them: simple high-confidence answers use ask_pipeworx_beta, deep grounded citations use ask_pipeworx_grounded, and multi-part synthesis uses deep_research. This leaves no ambiguity about when to invoke this tool.

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

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

The description goes well beyond annotations by disclosing that no candidate is currently active, that the last one was retired on a specific date, and that the tool currently behaves exactly like the stable router. It also clarifies that there is no fallback layer and that it is a fully working router despite being experimental.

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 efficient, front-loading the core identity and then covering current state, usage, and experimental context in a few sentences. The exact tool count, retire date, and fallback note all contribute operational value without 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?

The description is complete for a tool of this complexity: it covers what the tool is, its current live state, how to invoke it, how it compares to the stable router, and the safety profile via annotations. Referencing ask_pipeworx as the baseline is acceptable because it is a named sibling tool.

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

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

Schema coverage is 100%, and all six parameters are documented as aliases for question. The description adds no further parameter-level detail beyond stating that arguments match ask_pipeworx, so the schema carries the parameter semantics and the description neither helps nor hurts.

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

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

The description clearly identifies this as a beta version of ask_pipeworx and as a universal router with the same tool surface and response shape. It distinguishes it from the stable router through candidate routing improvements and its experimental edge, though it never directly states that the tool answers questions by routing them.

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

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

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 inform merges. It gives a clear selection context, though it does not explicitly name ask_pipeworx as the alternative for stable production use.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: the exact success return shape including verbatim evidence and confidence, the refusal contract with the full enumeration of refusal_reason values, and the cost/performance tradeoff. It also explains the non-hallucination guarantee (answer extracted ONLY from tool result). Nothing contradicts the annotations.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, success return shape, refusal return shape, usage scenarios, and cost tradeoff. The key differentiator ('hallucination-resistant') is front-loaded, and the guidance sentences are ordered from when-to-use to when-not-to-use. No filler or repetition of schema 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?

With no output schema present, the description fully compensates by documenting both the success return object and the refusal object with its enum values. It covers cost, routing scope, evidence mechanism, and selection criteria. For a grounded question-answering tool, nothing an agent needs to invoke it correctly or interpret its result is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 — the schema already documents the 'question' parameter and its aliases. The description adds process context (how the question is routed and answered), which is mildly useful for formulating queries, but it does not add parameter-level detail such as format expectations or examples. The schema carries the heavy lifting here.

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 leads with a specific verb-plus-resource framing: 'Hallucination-resistant answer mode for high-stakes reads.' It states exactly what the tool does — routes a question across 5,798 tools and 1,517 sources, fetches data, and extracts an answer using only the tool result content. It explicitly differentiates from the sibling ask_pipeworx by naming it and describing the grounded-extraction difference, so an agent can distinguish them without opening schemas.

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

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

Explicit when-to-use guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also states the when-not-to-use condition — 'prefer ask_pipeworx for casual lookups' — along with the cost reason (one extra LLM call). Both the selection condition and the alternative are 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?

The annotations already indicate read-only, open-world, and idempotent behavior. The description adds extensive behavioral details: resolver contract with confidence levels, fan-out logic, response shapes, safety short-circuits for low confidence or closed markets, and resolution-rule risk. No contradictions; the description enriches the annotation 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 structured with clear sections (classifiers, fan-out examples, response shapes, etc.) and is front-loaded with the core purpose and use cases. However, it is quite lengthy and could be more concise by trimming redundant explanations (e.g., repeated mentions of low-confidence paths).

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 absence of an output schema, the description thoroughly covers all return value shapes (market, analysis, evidence, resolver contract, parent event, news fields, safety indicators, cancellation rules). It addresses edge cases like low confidence, closed markets, wide spreads, and resolution rules, making it fully actionable for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description provides additional context beyond the schema: explains that 'market' accepts slug, URL, or question text; 'depth' describes the trade-off between quick and thorough; 'include_raw' explains when to use true vs false and the impact on response size. This adds significant 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?

The description starts with a clear statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It identifies the specific verb 'Research', the resource 'Polymarket bet', and distinguishes itself from sibling tools like polymarket_edges by targeting bet-specific research with use-case examples.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides concrete examples but does not explicitly name alternatives or state when not to use it, leaving a minor gap in differentiation from siblings like polymarket_arbitrage or deep_research.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that results are capped by OpenCellID, a behavioral trait not covered by annotations. No contradictions.

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

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

Two sentences that front-load the purpose and format, then add a critical limitation. No unnecessary words—every sentence adds value.

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

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

Given the presence of an output schema, the description sufficiently explains the tool's operation and limitations. Could mention pagination or response structure, 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?

Schema coverage is 100%, so the schema already describes all parameters. The description reiterates the bbox format and adds context on caps, but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the verb 'List' and resource 'cell towers' with a bounding box. It distinguishes from sibling tools like 'get_cell' which retrieves a single cell, and other unrelated tools.

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

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

Provides guidance on narrowing the bounding box due to server-side caps, but does not explicitly state when to use versus alternatives like 'get_cell'. The context about caps is helpful for effective use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: it explains that for 'company' it pulls latest 10-K revenue/net income/cash/debt with correct off-calendar fiscal year handling, and for 'drug' it pulls FAERS adverse-event counts, FDA approvals, active trials. It also states results are sorted by primary metric and returns paired data with 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, front-loaded paragraph with example queries that immediately convey the tool's function. Every sentence adds value: usage guideline, entity-specific data details, output format, and efficiency claim. No redundant or filler 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?

Given the tool's complexity (multiple entity types, multiple data sources, comparison logic), the description is remarkably complete. It covers input requirements, data sources, special cases (off-calendar fiscal years), output format (paired data + citation URIs), and efficiency gains. No significant gaps are present.

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

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

Schema coverage is 100%, but the description enriches parameter meaning: for 'type', it specifies what data each enum value retrieves (SEC EDGAR/XBRL vs FAERS/FDA/clinicaltrials). For 'values', it explains expected formats (tickers/CIKs for companies, drug names for drugs) and the 2-5 limit, providing practical guidance beyond the schema's 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 starts with multiple query examples ('Compare X and Y', 'X vs Y', etc.), clearly stating the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from sequential single-pack lookups, making the verb 'compare' and resource 'entities' unambiguous.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear when-to-use directive. Also details entity types ('company' vs 'drug') and what data each pulls, helping the agent decide when to invoke this tool vs alternatives like entity_profile.

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 annotations, the description discloses many behavioral traits: account requirement, paid tier for 'thorough', 15-90s latency, gap[] reporting, contradictions[] scans, guaranteed-fetchable citation_uri, and semantic excerpting rather than head-truncation. It also states that findings are 'never invented'. No contradiction with annotations was found.

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

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

Though long, the description is densely packed with high-value information and each sentence earns its place: auth requirements, sibling routing, scope, output guarantees, depth behavior, citation semantics, and latency. The most decision-critical information (account required, alternative tool) is front-loaded, and the rest is organized logically. This length is appropriate given the tool's complexity and the absence of an output schema.

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

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

For a tool with no output schema, the description is remarkably complete: it explains the findings packet, gaps[], contradictions[], citation_uri fetchability, hop field, deep-record excerpting, latency, and tier differences. Combined with a fully covered input schema and accurate annotations, an agent has nearly everything needed to decide whether to call this tool and what to expect. The only minor absence is a concrete JSON shape, but the description describes the return contract well enough.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents both question and depth including the quick/standard/thorough semantics. The description adds meaningful value by tying 'thorough' to a paid plan, explaining hop/gap-recovery behavior, describing latency expectations, and giving concrete example questions. It does not need to add syntax details because the schema already provides those.

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

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

The description states a specific verb-resource pair: it performs grounded, multi-source research across Pipeworx's structured data sources. It clearly distinguishes itself from open-web search and from ask_pipeworx by positioning itself for broad/multi-part questions while directing single lookups to the sibling. The mechanism (facet decomposition, parallel routing, findings packet) makes the tool's function 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: use it for broad/multi-part questions over structured data, and use ask_pipeworx instead for single lookups. It also handles the non-signed-in case by redirecting to ask_pipeworx, and clarifies tier-based depth availability. This is strong alternative-routing with concrete conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns top-N most relevant tools with names, descriptions, and full input schemas with curated examples, ready to call directly. This enriches behavioral context without contradicting annotations.

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

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

The description is relatively concise given the amount of useful information. It front-loads the main purpose and domain list, then explains output and usage hint. A few sentences could be tightened, 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?

For a discovery tool with multiple parameters and no output schema, the description fully explains the output (top-N tools with schemas, ready to call) and usage context. No gaps given the tool's role.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions aliases for 'query' but doesn't add significant meaning beyond the schema. The parameter descriptions in the schema are already adequate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains and explicitly distinguishes it from siblings by advising 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description gives explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: [list]' and instructs to call this first to see options, implying not for single answers. This helps differentiate from sibling tools.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing fan-out sources, soft-failure of the USPTO PatentsView API, expected empty results for companies without biologics, and the meaning of sources_used/sources_failed. It also explains the resolved:false behavior for private companies, which is valuable context not present in annotations.

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

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

The description is long but dense and front-loaded with the purpose and routing instruction before enumerating outputs. Some sentences are run-on, but nearly every clause carries useful information about sources, failure modes, or expected results, so the length is justified.

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

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

For a complex multi-source tool with no output schema, the description covers inputs, output structure, source-specific caveats, empty-result semantics, and failure handling. An agent has enough context to decide when to call it and what to expect from the 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?

The schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds extra clarity by stating that type accepts 'company' or 'ticker' interchangeably, and by explicitly enumerating ticker, zero-padded CIK, and company name as valid value forms with examples. This is useful reinforcement 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 leads with concrete user queries and states the core function: a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes this from single-pack SEC/XBRL/news lookups, making the tool's scope and resource immediately identifiable.

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 an explicit routing rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies the accepted input forms and the expected behavior for private companies, giving the agent clear conditions for when to call this tool.

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

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

Annotations already provide destructiveHint and idempotentHint. The description adds context about clearing sensitive data and that the tool is used for deletion, which aligns with annotations. No contradiction.

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

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

Two sentences, no wasted words. First sentence clearly states purpose, second provides usage context. Front-loaded and efficient.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and related tools. No gaps.

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

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

Schema coverage is 100% and the parameter 'key' is described as 'Memory key to delete' in the schema. The description does not add extra semantics beyond what is already in 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 states 'Delete a previously stored memory by key' which clearly identifies the verb and resource. It also mentions pairing with 'remember' and 'recall', distinguishing it 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?

Explicitly specifies when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. This helps the agent decide when to invoke this tool over alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds concrete steps: fetches the page, extracts title/description/key links, and emits standard markdown format. No contradictions.

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

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

Description is three sentences, front-loaded with core action, followed by use cases. Every sentence is informative and there is no superfluous 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 lacking an output schema, description fully explains output format (text blob for site-root/llms.txt). Process is summarized, use cases are covered, and annotations ensure safety understanding.

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 adds examples (e.g., 'https://example.com') and default/max values for max_links, providing added value beyond schema.

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

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

Description clearly states the action (generate a production-ready llms.txt file) and the resource (any URL). It specifies the exact output format and distinguishes from sibling tools which are all research or utility tools, none generating llms.txt.

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 lists three common use cases (indexing a client's site, drafting for own project, auditing a competitor). While it does not state when not to use, the specificity makes its application 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool returns lat/lon, range, samples, and radio type, which is helpful but does not disclose potential errors, rate limits, or data freshness. For a read-only tool with robust annotations, this is adequate but not rich.

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

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

The description is two sentences long: the first states the core action, the second defines acronyms and lists return fields. It is concise, front-loaded, and contains no superfluous 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?

The tool has an output schema, so detailed return value documentation is not required. However, the description lists return fields but does not explain terms like 'samples' or 'range' in context. For a simple geolocation tool, it covers the basics but could be more informative.

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, with each parameter clearly described (e.g., 'Mobile Country Code (e.g., 310 = US)'). The tool description defines acronyms (MCC, MNC, LAC) and mentions return fields, adding marginal value. Baseline for high schema coverage is 3, and the description does not significantly exceed that.

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 as geolocating a cell tower by mobile network identifiers. It lists the required identifiers (MCC, MNC, LAC, cell_id) and the return fields, distinguishing it from sibling tools like 'cells_in_area' (which finds cells by geographic area).

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. While the sibling 'cells_in_area' suggests a related but different functionality, there is no direct comparison or advice on choosing between them. Usage context is implied but not 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, destructiveHint=false, etc. Description adds value by detailing return fields (id, type, params, created_at, last_fired_at, fire_count) and specifying 'active' subscriptions, providing 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?

Two sentences with no wasted words. First sentence states purpose and return fields; second provides usage guidance. Highly efficient.

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

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

With full schema coverage, annotations covering safety traits, no output schema but return fields listed, and clear sibling tool context, the description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the single parameter (include_inactive) with a clear description. The tool description adds minimal extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource. Mentions returned fields (id, type, params, etc.), and distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

Explicitly tells when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear guidance on usage context and differentiates from subscribe/unsubscribe.

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

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

With all annotation hints false, the description carries the full burden of behavioral disclosure. It transparently covers rate-limiting (5 per identifier per day), cost (free, doesn't count against quota), the claim_token flow for anonymous filing, and the consequence of misreporting (delays). No annotation 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 front-loads purpose in the first sentence, followed by usage guidance, exclusions, and mechanics. It is somewhat long (7 sentences) but every sentence contributes useful context, so it is appropriately sized rather than wasteful.

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

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

Despite lacking an output schema and safety annotations, the description covers all essential context: return behavior (claim_token), scope, rate limits, cost, and follow-up mechanism. It is fully adequate for a 4-parameter tool with no required parameters.

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

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

Schema coverage is 100%, with each parameter already documented. The description adds no new parameter semantics beyond the schema; it merely reiterates claim_token usage that the schema already explains. Baseline 3 is appropriate.

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

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

The description uses a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') that immediately establishes the tool's purpose. It also distinguishes from sibling tools by explicitly limiting scope to this Pipeworx connection and listing concrete use cases (bug, feature, data_gap, praise).

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 criteria ('Use when a tool returns wrong/stale data...') and a clear exclusion ('if the tool came from a different MCP server... file it with that server instead'). It also offers a disambiguation rule for uncertain agents ('Pipeworx tool names are the ones this connection lists'), making usage guidance exceptionally 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds self-aggregating signal, no PII, caching details. 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?

Concise, well-structured: purpose first, then uses, then technical details. 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?

No output schema but describes return values (top tools, packs, volume). Includes caching and privacy details. Complete for its purpose.

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 window param with description. Description adds semantic context: shorter windows for hot, longer for steady-state. Adds value beyond schema.

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

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

Clearly states it returns top tools, packs, call volume over a window. Differentiates from siblings by focusing on aggregated usage trends.

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 lists three use cases: discovering hot data sources, confirming canonical tool, aligning use case. Lacks explicit when-not or alternatives, but context is helpful.

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 substantial behavioral context: how it searches (top ~200 markets, walks child markets), the semantic anchor threshold, partition filter logic, response structure, and fill check details. No contradiction with annotations; description enriches them.

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

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

The description is lengthy but well-structured with clear sections for each mode, semantic anchor, partition filter, response, and fill check. It is front-loaded with the main purpose. While it could be slightly more concise, every sentence adds value and there is no redundancy.

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

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

Given the complexity of the tool (multiple modes, fill check, no output schema), the description is remarkably complete. It explains the criteria for valid arbitrage signals, the fill check logic to avoid non-tradeable opportunities, and the response structure. It also references a sibling tool for custom sizing, covering all necessary context.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema by providing examples of event slugs (like 'fed-decision-may-2026'), topic seeds (like 'Fed rate decision'), and URL acceptance. It also clarifies that passing no args triggers a different mode. However, schema already captures the essential types and descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes: trending scan with no args, event mode for a specific slug, and topic mode for cross-event scanning. The verb 'find' and resource 'arbitrage opportunities' are specific, and the description distinguishes the tool 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?

The description provides explicit guidance on when to use each mode: no args for trending scan, event (recommended for a specific market), and topic for cross-event scanning. It explains the semantic anchor (Jaccard >= 0.30), partition filter (placeholder slugs), and fill check to avoid non-realizable trades. It also references polymarket_fill_risk for custom sizing.

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 provides extensive behavioral details beyond the annotations: it explains the three model families, edge calculation with slippage, Kelly sizing caps, Fed bet exclusion, caching behavior ('Cached 1h at the KV level keyed on all knobs'), and diagnostic output. This exceeds what the annotations (readOnlyHint, idempotentHint) 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 well-structured despite its length. It starts with a clear one-sentence purpose, then breaks down into logical sections: model families, opportunity fields, tradeable knobs, response structure, and caching. Front-loading is effective. Every sentence adds value given the tool's complexity.

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

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

The description is exceptionally complete. Given the lack of an output schema, it thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and each field within opportunities (edge_pp_net, kelly_fraction, market metadata, 24h-move warning). It also describes how empty segments are handled via diagnostics, making the tool self-explanatory.

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

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

Although the schema already covers all parameters (100% coverage), the description adds significant meaning: it explains the rationale for default values (e.g., slippage_pp: 'Polymarket has zero trading fees... but bid/ask + thin depth typically eats 20-50bp per trade'), clarifies the purpose of tradeable-edge knobs, and provides usage guidance for parameters like min_liquidity and max_spread_pp. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The verb 'scan/return' and the resource 'Polymarket markets' are explicitly mentioned, and the phrase 'what should I bet on today' distinguishes it from siblings like polymarket_arbitrage or polymarket_fill_risk.

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

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

The description gives clear usage context: 'Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets.' It implies the tool is for initial opportunity discovery, but it does not explicitly state when not to use it or compare it to sibling tools. However, the context is sufficient for an agent to understand its primary use case.

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 valuable behavioral details: response structure (tracked[], expired[], snapshot_dates[]), decay computation on |edge_pp_net|, and sign convention (negative = SELL YES). 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 a clear front-loaded purpose and sections for response details and limits. It is somewhat verbose but every sentence adds value. Minor point: could be slightly more concise, but structure compensates.

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 response fields (tracked[], expired[], snapshot_dates[]) and their content. It also notes limitations (60-day TTL, start date, decay from daily closes). For a moderately complex tool, this is comprehensive.

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

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

Input schema coverage is 100% with descriptions for both parameters (days, window). The description adds context: default values, clamping (2-30), window options, and explanation of snapshot triggers. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series tracking and decay, answering 'how long has this edge existed and is it shrinking?'

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 context on when to use the tool (analyzing edge persistence) and explains trade significance. It does not explicitly list alternatives or when not to use, but the context is clear. The LIMITS section provides constraints on history depth and decay computation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral detail: it walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), and for basket mode reveals forced_directional_risk and the danger of partial fills. This is valuable context beyond the annotations.

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

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

The description is well-structured with clear sections for REQUIRES, SINGLE-MARKET, and BASKET modes. It is lengthy (~300 words) but every sentence adds value. Minor conciseness could be achieved by further splitting, but overall it balances detail with clarity.

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

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

Given the tool has no output schema and handles two complex modes, the description is remarkably complete. It lists all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains risks (thin legs, forced directional risk). It covers edge cases like partial basket fills and maximum safe notional.

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 enhances understanding by explaining how size_usd is interpreted differently (spend vs target proceeds, settlement notional) and how side defaults are determined in basket mode. This adds meaning but 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 clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and specifies two modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly recommending its use before acting on their 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 provides explicit guidance on when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why alternative tools or actions may fail due to thin books and partial basket fills converting arb into directional positions.

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 behavior, and the description adds substantial non-obvious context beyond that: compatibility warnings can be non-empty even when pairs are returned, pairing_unverified is always set, spreads are gross fees-not-modeled, temporal_alignment null has specific meaning, and unclassified legs are never paired. This is exactly the kind of behavioral disclosure an agent needs.

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 length is justified by the tool's complexity and the absence of an output schema. It is organized into clear sections: modes, response, safety fields, fees, and skip counters, with the core purpose front-loaded. Some redundancy exists, such as repeating the topic list that the schema already documents, so it is not maximally concise.

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

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

With no output schema, the description carries full responsibility for explaining return semantics, and it does so thoroughly: matched spreads, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped_cross_type/subtype counters are all described. It also clarifies ambiguous cases like null temporal alignment and non-empty warnings, so the agent can interpret results correctly.

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

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

The input schema already provides 100% coverage: `topic` documents the full enum list, and both explicit parameters document that they override the topic-mapped side. The description reinforces the two-mode semantics and says both modes share the same matcher, but it does not add substantial per-parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a precise resource and task: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from Polymarket-only or Kalshi-only siblings, and it specifies the matching criterion (same outcome on both venues) rather than leaving the scope vague.

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 strong mode-based guidance: use `topic` for 10 pre-mapped shortcuts, or use explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, and notes both modes run identically. It also warns that pre-mapped shortcuts are not necessarily tradeable. However, it does not explicitly state the precondition that at least one mode must be selected, nor does it name alternative tools to prefer in other situations.

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?

Behavioral traits like read-only, idempotent, and non-destructive are already provided by annotations. The description adds useful context about scoping ('scoped to your identifier') and the tool's relationship with 'remember' and 'forget'.

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 (three sentences) and front-loaded with the main action. Every sentence adds value with no redundancy or filler.

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

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

For a tool with one optional parameter, no output schema, and comprehensive annotations, the description covers retrieval, listing, scoping, and pairing with sibling tools, making it complete 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?

The schema already describes the single parameter, but the description adds crucial semantic information: omitting the key lists all keys. This goes beyond the schema's documentation of the parameter.

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: retrieving a value by key or listing all keys if omitted. It uses specific verbs ('retrieve', 'list') and distinguishes itself from sibling tools like 'remember' and 'forget'.

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

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

The description provides clear context on when to use the tool (to look up stored context) and mentions complementary tools (remember, forget), though it does not explicitly state when not to use it.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds key behaviors: marking events as read (mark_read), returning specific fields (source, citation_uri, payload), and confirming polling suitability. 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 (two main sentences plus a note about an alternative endpoint). It is front-loaded with the core purpose and each sentence provides necessary detail without repetition.

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

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

Given the tool's simplicity (no required parameters, no nested objects, no output schema), the description covers what is returned, filtering options, state-changing parameter behavior, and an alternative method. It is complete for an agent to understand and use the tool.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaning by explaining the effect of mark_read, giving an example filter (sec_8k), and clarifying that since expects an ISO timestamp. This adds value beyond the schema.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts. It distinguishes itself from sibling tools like list_subscriptions (which lists subscriptions) and subscribe/unsubscribe (which manage subscriptions) by focusing on event retrieval.

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

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

The description provides guidance on when to use this tool (e.g., polling works fine) and mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or contrast with alternatives like search tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds detailed behavioral traits: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and return format (structured changes[] grouped by source). 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?

Description is somewhat long but every sentence adds value. It is front-loaded with example queries, then details fan-out behavior and return format. Well structured but could be slightly more concise 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?

Given no output schema, the description adequately explains the return: 'Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' Covers all aspects of a complex multi-source tool with fallback behavior.

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 adds meaning beyond schema: explains `since` accepts ISO date or relative shorthand with examples, suggests typical monitoring value, and clarifies `value` can be ticker or CIK. Adds 'only company supported' for `type`.

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 provides a 'change feed for a company' with examples like 'What's new with X'. It specifies the verb 'change feed' and the resource 'company', and distinguishes from the sibling entity_profile tool by explaining that entity_profile is for static profiles.

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

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

Explicitly says when to use this tool (change feed) and when not to (use entity_profile for static profile). Provides guidance on `since` parameter: 'Use "30d" or "1m" for typical monitoring.'

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

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

The description adds context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. Annotations already indicate idempotency and non-destructiveness. 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 concise and front-loaded with the primary purpose. Every sentence adds value, from usage context to storage details. No wasted words.

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

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

For a simple set operation, the description covers purpose, when to use, scoping, and persistence. No output schema is needed; the return is implied. Missing minor details like overwrite behavior, but still fairly complete.

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

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

Schema coverage is 100%, and the description adds context by explaining that key-value pairs store findings with examples (subject_property, target_ticker). This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It provides specific examples (resolved ticker, target address) and distinguishes from siblings 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?

The description explicitly says when to use: 'when you discover something worth carrying forward.' It mentions pairing with recall and forget, but does not explicitly state when not to use it or list alternatives beyond siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description enriches this considerably: it discloses the multi-endpoint cascade ('Each call cascades through several lookup endpoints internally'), the graceful degradation when GLEIF/OpenFIGI are unavailable, the explicit `unresolved` field for identifiers that could not be resolved, and the `figi_candidates` behavior on ambiguity. This goes well beyond annotations and prepares the agent for real-world failure modes.

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

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

The description is long (over 300 words) but highly information-dense. It is structured into clear segments (supported types, behavior notes) and front-loads the core action and usage rule. Every sentence adds either a capability, a caution, or a fallback behavior. Minor redundancy exists (e.g., repeating 'figi_candidates' twice), but overall the length is justified for a tool that spans multiple identifier systems and edge 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?

For a tool with no output schema and two interdependent parameters, the description covers everything an agent needs: both entity types, input formats (ticker, CIK, ISIN, name), the exact rule for bond issuer names, what identifiers are returned and from which source, the ambiguity handling, and the graceful-degradation path. It even explains that it replaces 2-3 manual lookups, framing its role in the workflow. 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% with both parameters described, but the description for `value` is exceptionally detailed: it explains the entity-name-only rule with a concrete bond example ('NEW YORK ST DORM AUTH' vs. 'NEW YORK ST DORM AUTH revenue bonds'), clarifies that a ticker or CIK can also be passed, and even mentions how ISINs resolve to legal entities. This adds meaning beyond the schema's short one-liners and prevents common misuse.

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 concrete example queries, then states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly distinguishes itself from siblings by being the go-to resolution tool, and the supplementary detail about supported types (company/drug) and the specific identifiers returned (CIK, ticker, LEI, FIGI, RxCUI) leaves 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 first line after the examples says 'Use FIRST whenever you have a name but need an ID.' This is explicit guidance on when to invoke it. It also provides a decision rule for 'company' type with 'IMPLIED vs. name-search', and clarifies that ambiguity is handled by returning candidates. It does not name alternative tools, but given the sibling list, none serve the same resolving purpose, so the guidance is sufficient and 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 (readOnlyHint, idempotentHint, etc.) already convey safety. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density per entity. This supplements the annotations well.

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

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

The description is two sentences that front-load the core purpose and then detail functionality and use case. It is fairly concise, though the second sentence is a bit long. No filler or repetition.

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

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

Given no output schema, the description covers return values (ranked list with score, confidence, signal density). It also describes internal behavior (calling ai_visibility_check). It lacks details on error handling or limits, but the annotations cover safety. Overall complete for a benchmarking 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?

With 100% schema coverage, the description adds significant meaning: it explains the entities array's semantics (first is subject), that models default to workers-ai, that _apiKey is only needed for anthropic, and that context disambiguates common names. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying its competitive audit 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 explicitly recommends use for competitive AI-marketing audits and notes that the first entity is treated as the subject. While it does not directly advise against using alternative tools, the sibling list includes ai_visibility_check for single entities, and the context implies this is for multi-entity comparisons.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds important behavioral context: partial failures, bundlephobia latency (5-30s), and graceful degradation with sources_failed. This goes beyond annotations.

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

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

The description is well-structured and front-loaded. It is a bit long (two paragraphs) but every sentence adds value. Could be slightly more concise, 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 no output schema, the description fully explains return values: summary block (fields listed), per-advisory detail, links, and alternative versions. Also covers error handling (sources_failed). Complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds useful context: default version (latest) and acceptance of scoped packages (e.g., '@types/node'). Slightly above baseline.

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

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

The description clearly states the tool's purpose: a composite check for npm packages using deps.dev and bundlephobia. It uses specific verbs and resources ('is X safe / popular / small') and distinguishes itself from sibling tools like deps.dev:version.

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

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

Explicit when-to-use guidance: 'Use whenever an agent asks...'. Also clearly scopes to NPM ecosystem and mentions fallback for other ecosystems (PyPI, Maven, etc.) via deps.dev:version.

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

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

Goes beyond annotations by detailing: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and that passages include offsets for verification. 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?

Single well-structured paragraph front-loading purpose, then usage, then technical details. Every sentence adds value, though minor redundancy exists (e.g., character offsets mentioned twice).

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

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

Given no output schema, the description fully explains return values (top-N passages with offsets and scores), embedding model, windowing, and constraints. No gaps in essential behavior.

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

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

Schema has 100% coverage, so baseline is 3. Description adds value by explaining usage context (e.g., 'pass the text you already pulled') and mentioning truncation behavior, which 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 'Semantic search INSIDE a fetched record,' with a specific verb ('search') and resource ('fetched record'). It distinguishes from siblings by highlighting the context-saving benefit and pairing with ask_pipeworx_grounded.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt.' Provides alternatives and complementary tools (ask_pipeworx_grounded) for grounding over passages.

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

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

The description adds behavioral context beyond annotations, requiring OAuth, listing type-specific parameters, and describing delivery channel constraints (verification, rate limits, auto-disable). Annotations indicate idempotentHint=true but description does not clarify behavior on duplicate creation, which is a minor gap.

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 purpose and structured with clear sections. It is slightly dense but each sentence adds value; could be marginally more concise but is still 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 has 3 parameters, nested objects, and no output schema, the description covers purpose, parameters, delivery options, and constraints comprehensively. Return value is mentioned only as 'Returns the new subscription id' which is adequate but could be more detailed.

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 tool description adds value with examples and constraints for each parameter, especially for 'params' and 'delivery' which include type-specific formats and validation rules.

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 'Create a proactive monitoring subscription to a live-data event stream' and specifies that it returns the new subscription ID. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by defining the creation action.

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

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

The description provides clear context: requires a Pipeworx OAuth account, lists supported types with examples, and details delivery channels with constraints. It does not explicitly state when not to use this tool versus alternatives, but within the subscription tools group, the usage 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=true and destructiveHint=false. Description adds that it returns category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog. This provides rich 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?

Front-loaded with common user queries, followed by clear explanation. Slightly verbose with multiple synonyms, but each sentence adds value. Could trim redundancy 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?

Despite no output schema, the description explains return format (category-bucketed examples with tool+argument). Single optional parameter is fully documented. Additionally lists meta-tools, providing complete context for an onboarding tool.

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

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

Only one optional parameter 'topic' with full schema coverage. Description adds example values and usage context, but the schema already provides adequate description. Baseline 3 is appropriate.

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

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

The description uses specific verb+resource ('suggest questions') and lists multiple natural language triggers. It clearly distinguishes this as the onboarding entry point, contrasting with siblings like discover_tools or ask_pipeworx.

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

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

Explicitly instructs to use this tool FIRST when unsure of Pipeworx capabilities. Also explains optional topic parameter to focus the output. No exclusion guidance needed for an onboarding tool.

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

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

Beyond annotations, the description explains that the row is deactivated (not deleted) and historical events remain available, adding behavioral context that annotations do not cover.

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 action, no superfluous words. 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 tool with one parameter and no output schema, the description covers purpose, ownership, side effects, and references related tool (recent_alerts). 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%, and the description simply restates 'by id'. No additional semantics beyond schema, meeting baseline.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription by id'), clearly distinguishing it from siblings 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 mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding proper usage. Does not mention alternatives but context is clear.

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

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

The description adds critical behavioral context beyond the annotations: it explains the distinction between could_not_verify (the check did not happen, not evidence either way) and unsupported (no coverage), and discloses that returns include a verdict, the actual value with citation, and reasoning. It also notes the tolerance_pct override for hallucination detection. These details meaningfully supplement the readOnly/openWorld/idempotent 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?

The description is appropriately sized for the tool's complexity. It opens with concrete user query examples, then defines the action, explains the two routing paths, summarizes the output, highlights the crucial could_not_verify caveat, and closes with the efficiency benefit. Every sentence adds information; there is no fluff 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?

For a tool with two pipeline paths and nuanced verdict meanings, the description covers all essential details: the claim types (financial vs. other), the return structure (verdict, value, citation, reasoning), the special handling of could_not_verify and unsupported, and the tolerance override. It is complete enough for an agent to invoke correctly without an output schema, and it explains the optional parameter's impact.

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 described), so baseline is 3. The description elevates this by explaining tolerance_pct's purpose beyond the schema: it 'overrides the tolerance implied by the claim wording' and recommends setting 1–2% for hallucination detection. The claim parameter already has illustrative examples in the schema, so the description's additional examples are marginal but the tolerance_pct enrichment is valuable.

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 defines the tool as 'natural-language claim verification against authoritative sources' and lists recognizable query patterns like 'fact check' and 'is it true that'. It distinguishes itself by describing two routing paths (SEC EDGAR for company-financial claims vs. grounded pipeline for all others), making it clear this is a specialized claim-verification tool, not a general Q&A tool.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which gives clear guidance. It also explains the routing logic and notes that the tool 'replaces 4–6 sequential calls,' implying it should be preferred over composing other tools. However, it does not name specific sibling tools to exclude, so it lacks an explicit 'when-not-to-use' statement.

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